> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Read agent status and preflight agent dispatch through REST Public Preview.

Agents execute work inside OrgX with scoped tools, budget controls, and approval
gates. REST Public Preview exposes agent status and dispatch preflight checks.
Use MCP for full model-facing delegation.

## List Live Agents

```http theme={"dark"}
GET /api/client/live/agents
```

```bash theme={"dark"}
curl "https://useorgx.com/api/client/live/agents?include_idle=true" \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

### Query Parameters

| Parameter      | Type    | Description                                         |
| -------------- | ------- | --------------------------------------------------- |
| `initiative`   | string  | Optional initiative ID filter.                      |
| `include_idle` | boolean | Include idle specialist agents. Defaults to `true`. |

### Response

```json theme={"dark"}
{
  "agents": [
    {
      "id": "engineering-agent",
      "name": "Engineering",
      "domain": "engineering",
      "status": "running",
      "currentTask": "Review deployment plan",
      "progress": 60,
      "runId": "f0f8d5e1-6a1f-4f0c-9d93-1f7b7e7e1d23",
      "initiativeId": "0e7c4df9-0f58-45a0-9c43-0ccf21b27a7d",
      "startedAt": "2026-04-29T20:00:00Z",
      "blockers": [],
      "instanceCount": 1
    }
  ],
  "summary": {
    "total": 7,
    "running": 1,
    "queued": 0,
    "blocked": 0,
    "idle": 6
  }
}
```

## Preflight Agent Spawn

```http theme={"dark"}
POST /api/client/spawn
```

This endpoint checks quality gates and model-routing policy before a client
spawns or delegates work.

```bash theme={"dark"}
curl https://useorgx.com/api/client/spawn \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "engineering",
    "taskTitle": "Review API reference docs",
    "taskDescription": "Check public preview docs before submission."
  }'
```

### Request Fields

| Field             | Type   | Required | Description                                                                                     |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `domain`          | string | Yes      | Agent domain such as `engineering`, `product`, `marketing`, `sales`, `operations`, or `design`. |
| `taskId`          | string | No       | Existing task ID to preflight.                                                                  |
| `taskTitle`       | string | No       | Task title for ad hoc preflight.                                                                |
| `taskDescription` | string | No       | Additional task context.                                                                        |
| `entityType`      | string | No       | Optional entity type hint.                                                                      |

### Response

```json theme={"dark"}
{
  "ok": true,
  "allowed": true,
  "modelTier": "standard",
  "task": null,
  "data": {
    "allowed": true,
    "modelTier": "standard"
  }
}
```

## Full Delegation

For full AI-native delegation, use MCP:

* `orgx_spawn`
* `orgx_spawn`
* `orgx_spawn`