Execute an agent

Start an agent run (fire-and-forget). Returns the run ID. Rate-limited to 20/min. Supports JSON body or multipart/form-data with file uploads.

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

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

name*string

Query Parameters

version?string

Version query to execute (exact version, dist-tag, or semver range). When provided, the run uses the versioned manifest and prompt instead of the live agent.

Header Parameters

X-Org-Id?string

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

Formatuuid

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.

Lengthlength <= 255

Request Body

input?object

Run input values

modelId?string

Model ID override for this run. Takes priority over agent and org defaults.

proxyId?string

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

curl -X POST "https://loading/api/agents/string/string/run" \  -H "Content-Type: application/json" \  -d '{}'

{
  "runId": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "requestId": "string",
  "param": "string",
  "retryAfter": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string"
    }
  ]
}

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

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "requestId": "string",
  "param": "string",
  "retryAfter": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/idempotency-in-progress",
  "title": "Idempotency In Progress",
  "status": 409,
  "detail": "A request with the same Idempotency-Key is already being processed. Please wait and retry.",
  "code": "idempotency_in_progress",
  "requestId": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/idempotency-conflict",
  "title": "Idempotency Conflict",
  "status": 422,
  "detail": "This Idempotency-Key was already used with a different request body. Use a new key for different requests.",
  "code": "idempotency_conflict",
  "requestId": "req_abc123"
}

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