Planned Feature — Coming Soon

🚧 This feature is not yet released. The documentation below describes planned behavior and may change before launch.

Runs API

Start agent executions, stream events, and retrieve results.

Base URL: https://backend.flymy.ai/v1

Create Run

POST /agents/{agent_id}/runs

Field	Type	Required	Description
input	object	Yes	Input data matching agent's input_schema
revision_id	string	No	Run against a specific revision (default: published)

Example

curl -X POST https://backend.flymy.ai/v1/agents/agent_abc123/runs \
  -H "x-api-key: fly-***" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "topic": "AI agents in enterprise"
    }
  }'

Running a Marketplace Agent

Use the creator's username and agent slug:

curl -X POST https://backend.flymy.ai/v1/agents/creator-username/seo-auditor/runs \
  -H "x-api-key: fly-BUYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://mysite.com",
      "depth": "deep"
    }
  }'

Response

{
  "id": "run_xyz789",
  "agent_id": "agent_abc123",
  "revision_id": "rev_002",
  "status": "pending",
  "input": {"topic": "AI agents in enterprise"},
  "created_at": "2025-01-15T10:00:00Z"
}

Get Run

GET /runs/{run_id}

Response (Completed)

{
  "id": "run_xyz789",
  "agent_id": "agent_abc123",
  "status": "done",
  "input": {"topic": "AI agents in enterprise"},
  "output": {
    "summary": "AI agents are transforming enterprise workflows...",
    "key_findings": ["...", "..."],
    "sources": ["https://...", "https://..."]
  },
  "duration_ms": 14200,
  "created_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:00:15Z"
}

Response (Failed)

{
  "id": "run_xyz790",
  "status": "error",
  "error": {
    "type": "tool_error",
    "message": "browse_website failed: connection timeout"
  }
}

List Runs

GET /agents/{agent_id}/runs

Parameter	Type	Default	Description
limit	number	20	Max results
offset	number	0	Pagination offset
status	string	—	Filter: pending, running, done, error

Stream Events

GET /runs/{run_id}/events

Returns a Server-Sent Events (SSE) stream:

curl -N https://backend.flymy.ai/v1/runs/run_xyz789/events \
  -H "x-api-key: fly-***"

Event Format

event: planning
data: {"message": "Analyzing research topic..."}

event: tool_call
data: {"tool": "web_search", "arguments": {"query": "AI agents enterprise 2025"}}

event: tool_result
data: {"tool": "web_search", "result": "Found 15 results"}

event: reasoning
data: {"message": "Synthesizing findings..."}

event: completed
data: {"output": {"summary": "...", "sources": [...]}}

List Run Events

Retrieve all events after the run completes (non-streaming):

GET /runs/{run_id}/events/list

Response

{
  "events": [
    {"type": "planning", "message": "...", "timestamp": "2025-01-15T10:00:01Z"},
    {"type": "tool_call", "tool": "web_search", "arguments": {"query": "..."}, "timestamp": "2025-01-15T10:00:02Z"},
    {"type": "tool_result", "tool": "web_search", "result": "...", "timestamp": "2025-01-15T10:00:04Z"},
    {"type": "completed", "message": "Run finished", "timestamp": "2025-01-15T10:00:15Z"}
  ]
}

Error Types

Type	HTTP Code	Description
invalid_input	400	Input doesn't match agent's schema
agent_not_published	400	Agent has no published revision
not_found	404	Agent or run not found
rate_limit	429	Too many requests
tool_error	—	Tool call failed during execution
timeout	—	Run exceeded time limit
internal	500	Platform error