API referenceEndpoints

List runs

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agentrun/inbound/http.go`.

GET/v1/runs

Requires an authenticated tenant principal. Generated from the production route registered in internal/features/agentrun/inbound/http.go.

Authorization

bearerAuth
AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Query Parameters

schedule_id?string

Restrict the caller's own runs to those created by this schedule's fires (an agent_run scheduled task). Runs remain owner-only for every role; a malformed id is 404.

Formatuuid
conversation_id?string

Restrict the caller's own runs to those on this conversation — a thread of runs, newest first (a follow-up run joins the thread by sending the same conversation_id when it is created). Runs remain owner-only for every role, so another person's thread lists as an empty page; a malformed id is 404.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/runs"
{  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "status": "string",      "surface": {        "revision_id": "f8f7f022-982b-4bef-ba7d-4bb808fdbe2a",        "revision": 2,        "catalog_version": "1.1.0",        "created_at": "2019-08-24T14:15:22Z",        "refreshed_at": "2019-08-24T14:15:22Z"      },      "has_surface": true    }  ],  "next_cursor": "string"}

Create claim

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/runners/inbound/http.go`.

Create run from a request

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agentrun/inbound/http.go`.