API Overview

The platform API is the durable programmatic boundary for Agirunner.

If you are integrating another system, building custom operator tooling, or driving workflows without the dashboard, this is the surface that matters. The runtime executes work, but the platform API owns the control-plane records and contracts around that work.

Base URL

Most public routes live under:

/api/v1/...

Local development defaults:

• dashboard: http://localhost:3000
• platform API: http://localhost:8080

Authentication

Most routes require an API key-derived bearer token or the cookie-backed browser session used by the dashboard.

Header form:

Authorization: Bearer <token>

The token exchange and session routes are documented in Authentication.

Common Response Shapes

Single resource

{
  "data": {
    "id": "uuid",
    "name": "Example"
  }
}

Paginated list

{
  "data": [
    {
      "id": "uuid"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "pages": 3
  }
}

Error envelope

{
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "message": "Invalid request body: name is required",
    "recovery_hint": "optional, only when the domain error provides one",
    "details": {
      "issues": {
        "fieldErrors": {
          "name": [
            "Required"
          ]
        },
        "formErrors": []
      }
    }
  },
  "meta": {
    "request_id": "fastify-request-id",
    "timestamp": "2026-03-31T18:55:00.000Z"
  }
}

No work available

Some claim and polling routes intentionally return 204 No Content instead of an empty data object. That means the request succeeded, but there was nothing to claim or no state change to return.

Common Field Vocabulary

These names appear across most route families.

Field Term	Meaning
request_id	Caller-supplied idempotency and replay key for mutating writes. Reuse it only when retrying the exact same intended write.
workspace_id	Durable project or repository context the run operates against.
workflow_id	Top-level run record that owns work items, tasks, events, logs, and artifacts.
work_item_id	Mid-level unit of work inside a workflow, often mapped to a stage or branch of work.
task_id	Executable unit claimed by an agent or worker.
activation_id	One dispatch cycle or wake-up of workflow orchestration logic.
state	Current operational state of the resource itself, such as pending, in_progress, or completed.
lifecycle	Higher-level workflow lifecycle classification rather than task execution state.
input	Structured instructions or payload that the task is expected to work on.
context	Broader surrounding packet the runtime may need while executing, such as workflow, workspace, and attached documents.
metadata	Extra caller or system annotations that do not usually change control-plane semantics on their own.
created_at / updated_at	Server timestamps for creation and last mutation.

How To Read Contract Labels

The field tables in this API section use a compact contract vocabulary. If a field is documented as arbitrary JSON object, arbitrary JSON value, or opaque, treat it as flexible caller or platform data. If it is documented as a scalar, enum, UUID, or structured object, treat that shape as part of the contract.

Core labels

Label	Meaning
string	Free-form string. Unless the docs say otherwise, it is not a closed enum.
integer	Whole-number scalar.
boolean	true or false.
numeric scalar	Number field such as a timeout, count, or cost cap.
enum	Closed set of allowed values. The route schema or page lists the accepted values.
enum-like string	String field with a known current set of values, but not documented here as a permanently closed public enum.
fixed string	Literal string constant. The field is expected to always contain the documented value.
UUID	Canonical platform identifier.
URL string	URL-shaped string.
base64 string	Base64-encoded content payload.
string map	JSON object whose keys are strings and whose values are expected to be strings.
structured object	Object with documented subfields the platform interprets.
authored structured object	User-authored object with real product meaning, such as a playbook definition. It is not an arbitrary blob, even if the route accepts flexible JSON.
arbitrary JSON object	Caller-defined JSON object. The platform may store, sanitize, or display it, but only specifically documented keys have platform meaning.
arbitrary JSON value	Any JSON value, including scalar, array, or object.
opaque	Store it and send it back when asked, but do not parse business meaning from it.
server-generated	Read-only field produced by the platform. Clients should not try to author or control it.

Contract modifiers

Several field tables combine the core labels above with a few common modifiers:

Pattern	Meaning
<type>[]	Array of the given type.
<type> or null	The field may be absent as null even though its non-null value has a stricter type.
server-generated <type>	The platform owns the value and also guarantees the listed non-null type when it is present.
<type A> / <type B>	The field currently accepts or returns one of two primitive shapes, depending on route context.
<resource> record[]	Array of nested read-model records for that resource family, such as task record[] or activation record[]. The containing page documents the important subfields.

Common Query Conventions

The most common pagination contract in the API is:

• page: defaults to 1
• per_page: defaults to 20
• per_page max: 100

Several stream routes also use cursor-style fields such as after, after_cursor, or cursor.

Main Route Families

• Authentication
• Workflows
• Tasks
• Playbooks
• Workspaces And Artifacts
• Runtime And Fleet
• Logs And Streams
• Integrations
• Conventions And Errors

Integration Paths

Operator or service launching workflows

1. exchange an API key for a bearer token
2. look up a playbook and workspace
3. POST /api/v1/workflows
4. observe the run through workflow, work-item, and log routes

Runtime or worker execution

1. register an agent or worker
2. heartbeat regularly
3. claim work through task or worker routes
4. report completion, failure, logs, and lifecycle updates

External protocol integration

1. use A2A routes for task ingress and status
2. use ACP routes for session-oriented agent execution
3. use remote MCP routes for external tool surfaces

Integration Maturity

Remote MCP server management is already part of the main platform surface.

A2A and ACP are implemented in the platform today, but they should still be treated as early integration surfaces. The routes and core service logic exist, but they are still in active development and are not yet documented here as fully production-hardened protocol implementations. The Integrations page calls that out explicitly.

Scope Model

The route handlers enforce scope deliberately. Common scopes visible in the code are:

• admin
• agent
• worker
• service

That means the same API key should not be reused blindly across the dashboard, runtime, workers, and external automation. Route access is part of the platform contract.