Execute an inline agent (no persisted package)

Run an agent defined entirely in the request body. The platform creates a shadow packages row (ephemeral = true), runs it through the standard pipeline, and returns 201 + the created run resource (same shape as GET /runs/{id}; the shadow package id is the resource's packageId). Stream progress via GET /api/realtime/runs/{id}. The body is closed: an unknown field is a 400, never a silently dropped value — dependency_overrides in particular is NOT honoured on this surface and is refused rather than ignored. Caller-authored inline manifests require the read permission for each dependency type. Existing dependencies must be readable in an accessible source space (API keys remain pinned to their space), or belong to the readable system/catalog sources. Missing read permissions return 403; inaccessible existing sources return 404, before readiness checks or creation of a run. Nonexistent dependencies retain the normal validation errors. Permission: agents:write and agents:run — composing a manifest is authoring, launching it is running. A caller holding agents:run without agents:write — the operator and runner presets, an API key scoped to agents:run — is refused.

POST/api/runs/inline

Authorization

better-auth.session_token<token>

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

In: cookie

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

manifest*object

Full AFPS manifest (agent type). Give each inline run a concise, task-specific display_name in the user's language and a matching descriptive @inline/<kebab-case-slug> name — never an id or a generic label such as one-shot. All referenced skills/integrations must already exist in the org or system catalog — registry-only dependencies.

prompt*string

Contents of prompt.md — the agent's system prompt.

input?object

Run input validated against manifest.input.schema (AJV). File fields take upload://upl_xxx references (from createUpload), appfile://file_xxx references, or inline data:<mime>;name=<filename>;base64,<payload> URIs (≤4 MiB decoded) — same contract as POST /agents/{scope}/{name}/run.

context_files?array<string>

appfile://file_xxx URIs to mount read-only into the run's files/ directory — fan-in by reference, without declaring a file field in the manifest. The platform declares a reserved _context_files input field for them, so they go through the same ACL, byte/count caps and file_links chaining as any other file input, and are announced to the agent in its prompt. A manifest (or input) that already declares _context_files is rejected with a 400 — the name is reserved.

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.

modelId?string|null

proxyId?string|null

generation?

Per-run temperature/reasoning override, same contract as POST /api/agents/{scope}/{name}/run. Omitted properties inherit the manifest's model settings.

curl -X POST "https://your-instance/api/runs/inline" \  -H "Content-Type: application/json" \  -d '{    "manifest": {      "$schema": "https://schemas.afps.dev/v0/agent.schema.json",      "name": "@inline/summarize-attached-file",      "display_name": "Summarize attached file",      "version": "0.0.0",      "type": "agent",      "schema_version": "0.3",      "dependencies": {}    },    "prompt": "Summarize the attached file in three bullet points.",    "input": {      "audience": "engineering"    }  }'

{
  "id": "run_cm1abc123",
  "packageId": "@inline/r-abc12345-6789-4cde-8f01-23456789abcd",
  "userId": "usr_k7x9m2p4q1",
  "endUserId": null,
  "apiKeyId": null,
  "orgId": "org_r3t5w8y1z6",
  "spaceId": "spc_1d4e7a90-3c21-4b6f-8e05-6a9c2f7b1d38",
  "scheduleId": null,
  "status": "pending",
  "input": {
    "audience": "engineering"
  },
  "result": null,
  "artifacts": null,
  "checkpoint": {},
  "error": null,
  "metadata": null,
  "generation": null,
  "generation_override": null,
  "started_at": "2026-01-15T10:30:00Z",
  "completed_at": null,
  "duration": null,
  "cost": null,
  "cost_pricing_status": null,
  "unread": false,
  "runNumber": 1,
  "token_usage": null,
  "version_label": null,
  "version_ref": "draft",
  "proxy_label": null,
  "model_label": "Claude Sonnet 4",
  "model_source": "org",
  "runner_name": null,
  "runner_kind": null,
  "agent_scope": "@inline",
  "agent_name": "Summarize attached file",
  "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": true,
  "file_counts": {
    "input": 0,
    "output": 0
  },
  "inline_manifest": {
    "$schema": "https://schemas.afps.dev/v0/agent.schema.json",
    "name": "@inline/summarize-attached-file",
    "display_name": "Summarize attached file",
    "version": "0.0.0",
    "type": "agent",
    "schema_version": "0.3",
    "dependencies": {}
  },
  "inline_prompt": "Summarize the attached file in three bullet points."
}

{
  "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": "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",
  "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": "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"
    }
  ]
}

Execute an inline agent (no persisted package)

Authorization

Header Parameters

Request Body

Same Idempotency-Key still in flight

The organization's deletion is reserved

A declared integration has no usable connection