API Reference

REST API Reference

Manage workers, assign tasks, handle approvals, and query evidence programmatically. All endpoints live at https://api.agentfarms.in/v1.

Authentication

All API requests require a Bearer token. Generate one from Workspace → Settings → API Keys.

bash

# All requests require this header
Authorization: Bearer af_live_xxxxxxxxxxxxxxxxxxxx

# Base URL
https://api.agentfarms.in/v1

Keep your key secret

Never commit API keys to source code or expose them in client-side code. All keys are prefixed af_live_. Rotate from Settings if exposed.

Error format

All errors return a consistent JSON body:

400Validation error

json

{
  "error": {
    "code": "validation_error",
    "message": "worker_id is required",
    "field": "worker_id"
  }
}

Field	Type	Description
`400`	`Bad Request`	Missing or invalid parameters
`401`	`Unauthorized`	Missing or invalid API key
`403`	`Forbidden`	API key lacks access to this resource
`404`	`Not Found`	Resource does not exist
`409`	`Conflict`	Re-deciding an already-decided approval
`429`	`Rate Limited`	Too many requests — retry with backoff

Workers

Workers are role-based AI agents deployed into your workspace. Each worker has a defined role, tool access, and approval threshold.

List workers

GET/v1/workers

Return all workers in the workspace.

Parameter	Type	Description
`status`	`string`	Filter: active \| paused \| failed \| provisioning
`role`	`string`	Filter by role slug (e.g. backend-developer)
`limit` default: 20	`number`	Results per page (1–100)
`cursor`	`string`	Pagination cursor from previous response

200Success

json

{
  "workers": [
    {
      "id": "wkr_01HXYZ",
      "name": "Rex",
      "role": "backend-developer",
      "status": "active",
      "approval_threshold": "medium",
      "tasks_completed": 47,
      "tasks_active": 1,
      "created_at": "2026-05-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

Create a worker

POST/v1/workers

Deploy a new worker. Provisioning takes 30–60 seconds.

Parameter	Type	Description
`name`required	`string`	Display name for this worker (e.g. Rex)
`role`required	`string`	Role slug — see worker roles reference
`workspace_id`required	`string`	Workspace to deploy into
`repo_ids`	`string[]`	Repo IDs the worker may access (code roles)
`approval_threshold` default: medium	`low \| medium \| high`	Minimum risk level that triggers approval
`persona`	`object`	{ display_name, email } — worker identity in connected tools

json

{
  "name": "Rex",
  "role": "backend-developer",
  "workspace_id": "ws_01HXYZ",
  "repo_ids": ["repo_abc123"],
  "approval_threshold": "medium",
  "persona": {
    "display_name": "Rex",
    "email": "rex@yourcompany.com"
  }
}

201Worker created

json

{
  "worker": {
    "id": "wkr_01HXYZ",
    "name": "Rex",
    "role": "backend-developer",
    "status": "provisioning",
    "created_at": "2026-05-30T09:00:00Z"
  }
}

Get a worker

GET/v1/workers/:id

Get full worker details including status and usage stats.

200Success

json

{
  "worker": {
    "id": "wkr_01HXYZ",
    "name": "Rex",
    "role": "backend-developer",
    "status": "active",
    "approval_threshold": "medium",
    "connectors": ["github", "jira", "slack"],
    "tasks_completed": 47,
    "tasks_active": 1,
    "tasks_failed": 2,
    "last_active_at": "2026-05-30T08:55:00Z",
    "created_at": "2026-05-01T09:00:00Z"
  }
}

Update a worker

PATCH/v1/workers/:id

Update worker name, approval threshold, or persona.

Parameter	Type	Description
`name`	`string`	New display name
`approval_threshold`	`low \| medium \| high`	Updated approval threshold
`persona`	`object`	Updated persona fields

Retire a worker

DELETE/v1/workers/:id

Retire a worker. Active tasks complete before removal.

200Success

json

{ "success": true }

Tasks

Tasks are units of work assigned to a worker. The worker plans, executes, and captures evidence for every task.

Assign a task

POST/v1/tasks

Assign a task to an active worker.

Parameter	Type	Description
`worker_id`required	`string`	Target worker
`description`required	`string`	Natural language task description. Be specific and bounded.
`repo_id`	`string`	Repository context for code tasks
`priority` default: normal	`low \| normal \| high`	Task priority affecting queue order
`metadata`	`object`	Arbitrary key/value metadata attached to this task
`webhook_url`	`string`	Override webhook URL for this task only

json

{
  "worker_id": "wkr_01HXYZ",
  "description": "Fix the /api/users email validation. Return clear 400 errors for invalid formats. Add or update tests.",
  "repo_id": "repo_abc123",
  "priority": "normal",
  "metadata": { "jira_ticket": "ENG-482" }
}

201Task queued

json

{
  "task": {
    "id": "tsk_01ABCD",
    "status": "queued",
    "worker_id": "wkr_01HXYZ",
    "priority": "normal",
    "estimated_completion": "2026-05-30T09:20:00Z",
    "created_at": "2026-05-30T09:01:00Z"
  }
}

Get task status

GET/v1/tasks/:id

Poll task status, progress, and outputs.

200Completed task

json

{
  "task": {
    "id": "tsk_01ABCD",
    "status": "completed",
    "worker_id": "wkr_01HXYZ",
    "progress": 1.0,
    "risk_level": "medium",
    "actions_taken": 7,
    "approvals_required": 1,
    "approvals_granted": 1,
    "outputs": {
      "pr_url": "https://github.com/org/repo/pull/482",
      "pr_title": "Fix: email validation in /api/users",
      "tests_added": 3
    },
    "evidence_url": "https://api.agentfarms.in/v1/evidence?task_id=tsk_01ABCD",
    "started_at": "2026-05-30T09:02:00Z",
    "completed_at": "2026-05-30T09:18:00Z"
  }
}

List tasks

GET/v1/tasks

List tasks with optional filters.

Parameter	Type	Description
`worker_id`	`string`	Filter by worker
`status`	`string`	Filter: queued \| planning \| executing \| awaiting_approval \| completed \| failed \| cancelled
`from`	`ISO 8601`	Created-at start range
`to`	`ISO 8601`	Created-at end range
`limit` default: 20	`number`	Results per page (1–100)

Cancel a task

POST/v1/tasks/:id/cancel

Cancel a queued or in-progress task. Evidence is preserved.

200Cancelled

json

{ "success": true }

Approvals

When a worker reaches an action above your approval threshold, it pauses and creates an approval request.

List approvals

GET/v1/approvals

List approval requests in your workspace.

Parameter	Type	Description
`status` default: pending	`string`	pending \| approved \| rejected \| expired
`worker_id`	`string`	Filter by worker
`risk_level`	`string`	Filter by risk: low \| medium \| high
`limit` default: 20	`number`	Results per page

200Approval list

json

{
  "approvals": [
    {
      "id": "apr_01HXYZ",
      "task_id": "tsk_01ABCD",
      "worker_id": "wkr_01HXYZ",
      "action_type": "merge_pr",
      "risk_level": "medium",
      "status": "pending",
      "action_payload": {
        "pr_url": "https://github.com/org/repo/pull/482",
        "pr_title": "Fix: auth timeout in billing retries",
        "files_changed": 3
      },
      "expires_at": "2026-05-31T09:00:00Z"
    }
  ]
}

Decide on an approval

PATCH/v1/approvals/:id

Approve or reject a pending action. Decisions are final (409 on re-decision).

Parameter	Type	Description
`decision`required	`approved \| rejected`	Your decision
`note`	`string`	Optional feedback for the worker on rejection

json

{
  "decision": "approved",
  "note": "Looks good — proceed with the merge."
}

200Decision recorded

json

{
  "approval": {
    "id": "apr_01HXYZ",
    "status": "approved",
    "decided_at": "2026-05-30T09:15:00Z"
  }
}

Evidence

Query evidence

GET/v1/evidence

Query the append-only evidence trail.

Parameter	Type	Description
`task_id`	`string`	Filter to a specific task
`worker_id`	`string`	Filter to a specific worker
`event_type`	`string`	Filter by event type (e.g. action.executed)
`from`	`ISO 8601`	Start of time range
`to`	`ISO 8601`	End of time range
`limit` default: 50	`number`	Results per page (1–500)

Export evidence

GET/v1/evidence/export

Export a full evidence bundle as JSON or CSV.

Parameter	Type	Description
`task_id`	`string`	Export for a specific task
`from`	`ISO 8601`	Export range start
`to`	`ISO 8601`	Export range end
`format` default: json	`json \| csv`	Export format

Connectors

List connectors

GET/v1/connectors

List configured connectors and health status.

Add a connector

POST/v1/connectors

Add a new connector. See the Connectors guide for per-tool setup.

Remove a connector

DELETE/v1/connectors/:id

Remove a connector and revoke its credentials.

Rate limits

Field	Type	Description
`Starter+`	`60 req/min`	100 tasks/day
`Pro+`	`300 req/min`	500 tasks/day
`Enterprise`	`Custom`	Unlimited tasks

Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

← PreviousConnectors Next →Webhooks