Execute an agent

Start an agent run (fire-and-forget — the response does not wait for execution). Returns 201 + the created run resource — same shape as GET /runs/{id} — including the resolved model_label / model_source. Rate-limited to 20/min. The body is JSON. File-typed input fields (format: uri + contentMediaType in the agent's input schema) accept either of two forms: (1) an upload://upl_xxx reference from createUpload — stage the bytes first by PUTting them to the signed URL (see createUpload for the step-by-step recipe); or (2) an inline RFC 2397 data URI data:<mime>;name=<filename>;base64,<payload> with up to 4 MiB of decoded content (name is optional) — the single-call path for JSON-only clients such as MCP. Inline bytes are written to the run workspace as a file and the payload is stripped from the persisted run input (the stored value keeps only a data:<mime>;name=<doc>;base64, marker). Declared binary MIMEs are verified by magic-byte sniffing in both forms. Send rerun_from instead of input to replay a previous run's input — same files, new overrides — without re-uploading. The effective model is resolved at run creation with precedence: request modelId > agent model setting > org default model > system default. Without an explicit modelId, a change to the org default model between triggers applies to the next run — send modelId to pin a specific model per run. A run against a published version assembles its bundle from stored artifacts before the container starts, so a bad artifact fails the trigger rather than the run: 422 dependency_unresolved (a pin with no published version), 422 bundle_invalid (the stored archive cannot be assembled), 422 bundle_signature_invalid (rejected by AFPS_SIGNATURE_POLICY), or 500 bundle_integrity_mismatch (the stored bytes no longer match the integrity hash recorded at publish time — republish the package). No run row is created in any of those cases. The body is closed: an unknown field, or a field whose type does not match, is a 400 rather than a silently ignored value, and a malformed JSON body is a 400 rather than an input-less run. Send no body at all for a run whose input resolves entirely from stored values.

POST/api/agents/{scope}/{name}/run

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Path Parameters

scope*string

Package scope (e.g. @myorg)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Package name

Query Parameters

version?string

Which agent definition to execute: draft (the live editor working copy), published (the latest published version), or a version spec (exact version, dist-tag, or semver range). Omitted means the latest published version, and returns 404 no_published_version when nothing is published. draft requires WRITE authority on the package — the type's write permission in the package's home space — and answers 403 draft_not_writable otherwise: a working copy runs for the people who author it, everybody else runs what they published. The run object's version_ref states which definition executed. Ignored for system agents.

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

X-Space-Id?string

Space ID. Required for space-scoped routes (agents, runs, schedules, and space-scoped module routes). Not needed for API key auth (space resolved from key).

Appstrate-User?string

End-user ID (eu_ prefix) to execute the request on behalf of. API key auth only — rejected with 400 on cookie auth.

Appstrate-Version?string

API version override (format: YYYY-MM-DD). Defaults to the org's pinned version or the current platform version.

Idempotency-Key?string

Unique key for idempotent requests (max 255 chars). Prevents duplicate resource creation on retries. Cached for 24 hours, scoped to the organization and space: a repeat with the same method, URL and body replays the original response with Idempotent-Replayed: true, the same key with a different method, URL or body is 422 idempotency_conflict, and a concurrent duplicate is 409 idempotency_in_progress. Current permissions are checked again; run responses are projected using current visibility. This operation honours the header because it declares this parameter — operations that do not declare it refuse the header with 400 idempotency_not_supported rather than silently ignoring it (see the “Idempotency” section of the API description).

Lengthlength <= 255

X-Appstrate-Connect-Offers?string

Opt-in: when set to 1 and the actor holds integrations:connect, each actor-actionable item of a 409 missing_integration_connection also carries a ready-to-open connect_url (a single-use bearer link that connects AS the actor). Set only by clients that render the connect card or hand the link to that human.

Value in"1"

Request Body

application/json

input?object

Run input values, validated against the agent's input schema. File fields take upload://upl_xxx references (from createUpload), appfile://file_xxx references (an existing file the caller can read), or inline data:<mime>;name=<filename>;base64,<payload> URIs (≤4 MiB decoded).

rerun_from?string

Run id whose persisted input to replay on this run. Mutually exclusive with input (400 if both are sent). The referenced run must be visible in the caller's org + space scope (404 otherwise; end-users can only replay their own runs) and must belong to the agent being triggered (409 rerun_agent_mismatch). Staged upload:// inputs are materialized on the original run and rewritten in its persisted input as durable appfile:// references, so later reruns reuse the same files without depending on upload retention. Existing appfile:// inputs remain unchanged. Limitation: inline data: inputs are NOT replayable — their bytes are materialized into the original run's workspace and stripped from the stored input (only a payload-less marker is persisted), so replaying a run whose input carried an inline file returns 409 rerun_inline_input_unavailable. Stage the file with createUpload when the input must be replayable.

modelId?string

Model ID override for this run — a system model key or an org-model UUID. Pins THIS run to that model, taking priority over the full resolution cascade (request modelId > agent model setting > org default model > system default). Without it, the org default is resolved at run creation — not ahead of time — so changing the org default between triggers silently changes the model used by subsequent runs. Returns 404 when the referenced model does not exist. The response echoes the resolved model_label + model_source so callers can verify which model the run actually uses.

generation?

Per-run temperature/reasoning override. A custom temperature is rejected only when explicitly unsupported; a reasoning level is accepted only when explicitly supported. Omitted properties inherit the agent defaults.

proxyId?string

Proxy ID override for this run, or "none" to disable proxying. Takes priority over agent and org defaults.

connection_overrides?

Per-integration connection sets for THIS run (the launch-override layer). Map of sets: { "@scope/integration": ["<connection_id>", ...] } — 1..20 connections per integration, each carrying its own authKey. Always an ARRAY, even for a single id. Cascade, first layer with a set wins: admin pin → enforced org default → launch override (this run's picks, or the firing schedule's — a scheduled fire carries no run override) → member pin → soft org default → fallback (the caller's single OWN connection — a connection shared by another member is never bound without an explicit pick). Under an admin pin or an enforced org default the override must name a subset of that governing set, and binds exactly that subset; one naming any connection outside it is refused with override_outranked — drop it or choose within the set. Resolved at kickoff, persisted on runs.connection_overrides and snapshotted into runs.resolved_connections so the spawn loader + MITM credentials refresh honour the same set. A namespace bound to more than one connection exposes a REQUIRED connection argument on each of its tools, enumerating the connection labels. Empty arrays and ids that are not uuids are refused at the write (lib/launch-schemas.ts), and so is a key that names no integration the agent declares (400 invalid_request, param: connection_overrides). A set that cannot bind answers 409 missing_integration_connection, whose per-integration errors[].code is override_connection_unavailable (an id not accessible to the actor) or override_outranked.

dependency_overrides?

Per-run dependency version overrides (#666). Flat map: { "@scope/skill": "draft" | "<semver|dist-tag>" }. By default every skill in the agent's closure resolves against PUBLISHED versions honoring its manifest pin; an entry here overrides that for a single run — "draft" pulls the dependency's mutable working copy (the skill edit loop: edit → run → observe, no republish) and requires WRITE authority on THAT dependency (403 draft_not_writable naming it otherwise: an unpublished definition runs for its author, whichever package declared it), any other value replaces the pin with that spec. Run-scoped only (never stored in the manifest) and recorded on the run object so a run that consumed draft bytes is never mistaken for a reproducible one. An unsatisfiable pin (including a never-published dependency) returns 422 dependency_unresolved before the run starts — pass an override or publish the dependency to fix it. A key that names no declared skill or integration of the effective manifest is a 400 naming the key, and it is raised BEFORE the authority gate — a typo is a malformed request, not a missing grant.

curl -X POST "https://your-instance/api/agents/string/string/run" \  -H "Content-Type: application/json" \  -d '{    "input": {      "message": "Summarize my latest emails"    },    "dependency_overrides": {      "@test/test-skill": "draft"    }  }'

{
  "id": "run_cm1abc123def456",
  "packageId": "@acme/email-sorter",
  "userId": "usr_k7x9m2p4q1",
  "endUserId": null,
  "apiKeyId": null,
  "orgId": "org_r3t5w8y1z6",
  "spaceId": "spc_1d4e7a90-3c21-4b6f-8e05-6a9c2f7b1d38",
  "scheduleId": null,
  "status": "pending",
  "input": {
    "message": "Summarize my latest emails"
  },
  "result": null,
  "artifacts": null,
  "checkpoint": {},
  "error": null,
  "metadata": null,
  "generation": {
    "temperature": 0.2,
    "reasoning_level": "high"
  },
  "generation_override": {
    "temperature": 0.2,
    "reasoning_level": "high"
  },
  "started_at": "2026-01-15T10:30:00Z",
  "completed_at": null,
  "duration": null,
  "cost": null,
  "cost_pricing_status": null,
  "unread": false,
  "runNumber": 17,
  "token_usage": null,
  "version_label": "1.2.0",
  "version_ref": "1.2.0",
  "proxy_label": null,
  "model_label": "Claude Sonnet 4",
  "model_source": "org",
  "runner_name": null,
  "runner_kind": null,
  "agent_scope": "@acme",
  "agent_name": "email-sorter",
  "runOrigin": "platform",
  "contextSnapshot": null,
  "modelCredentialId": "mpc_8h2k4m6n",
  "connection_overrides": null,
  "dependency_overrides": null,
  "user_name": null,
  "end_user_name": null,
  "api_key_name": null,
  "schedule_name": null,
  "connections_used": null,
  "package_ephemeral": false,
  "file_counts": {
    "input": 0,
    "output": 0
  }
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Resource not found",
  "code": "not_found",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/rate-limited",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. Please try again shortly.",
  "code": "rate_limited",
  "request_id": "req_abc123",
  "retry_after": 30
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}