---
title: "Use Coordinator API"
url: "https://docs.caracal.run/api/coordinator/"
markdown_url: "https://docs.caracal.run/markdown/api/coordinator.md"
description: "Agent-session, service-agent, invocation, and delegation endpoints served by Coordinator."
page_type: "api"
concepts: []
requires: []
---

# Use Coordinator API

Canonical URL: https://docs.caracal.run/api/coordinator/
Markdown URL: https://docs.caracal.run/markdown/api/coordinator.md
Description: Agent-session, service-agent, invocation, and delegation endpoints served by Coordinator.
Page type: api
Concepts: none
Requires: none

---

Coordinator is served on port `4000`. It owns agent runtime state and delegation graph state.

## Health and Metrics

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Liveness check. |
| `GET` | `/ready` | Dependency and job readiness. |
| `GET` | `/metrics` | Service metrics. |

## Agent Management

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/zones/:zoneId/agents` | Create an agent session. |
| `GET` | `/zones/:zoneId/agents` | List agent sessions. |
| `GET` | `/zones/:zoneId/agents/:id` | Inspect one session. |
| `GET` | `/zones/:zoneId/agents/:id/children` | List child sessions. |
| `PATCH` | `/zones/:zoneId/agents/:id/suspend` | Suspend a session subtree. |
| `PATCH` | `/zones/:zoneId/agents/:id/resume` | Resume a suspended session subtree. |
| `DELETE` | `/zones/:zoneId/agents/:id` | Terminate a session. |

## Service Agents and Invocations

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/zones/:zoneId/agent-services` | Register or update a service agent. |
| `GET` | `/zones/:zoneId/agent-services` | List service agents. |
| `POST` | `/zones/:zoneId/agents/:id/heartbeat` | Refresh a service-agent lease. |
| `POST` | `/zones/:zoneId/invocations` | Create an invocation. |
| `GET` | `/zones/:zoneId/invocations/:id` | Inspect an invocation. |
| `PATCH` | `/zones/:zoneId/invocations/:id/start` | Mark an invocation running. |
| `PATCH` | `/zones/:zoneId/invocations/:id/cancel` | Cancel an invocation. |
| `PATCH` | `/zones/:zoneId/invocations/:id/complete` | Complete an invocation. |

## Delegation

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/zones/:zoneId/delegations` | Create a delegation edge. |
| `GET` | `/zones/:zoneId/delegations/active` | List active delegation edges. |
| `GET` | `/zones/:zoneId/delegations/inbound/:sessionId` | List inbound edges for a session. |
| `GET` | `/zones/:zoneId/delegations/outbound/:sessionId` | List outbound edges for a session. |
| `GET` | `/zones/:zoneId/delegations/:id/traverse` | Traverse a delegation edge. |
| `GET` | `/zones/:zoneId/delegations/:id/impact` | Compute revocation impact. |
| `GET` | `/zones/:zoneId/agents/:sessionId/effective-authority` | Compute effective authority for a session. |
| `PATCH` | `/zones/:zoneId/delegations/:id/revoke` | Revoke delegated authority. |

## SDK Lifecycle Endpoints

| Method | Path |
| --- | --- |
| `POST` | `/v1/begin` |
| `POST` | `/v1/end` |
| `POST` | `/v1/spawn-child` |
| `POST` | `/v1/exchange` |
| `POST` | `/v1/delegate-to-existing-agent` |
| `POST` | `/v1/revoke-delegation` |
| `POST` | `/v1/verify` |

SDKs usually call these endpoints through the language-specific Caracal client rather than direct HTTP.

## Next Step

Continue to [Use STS Endpoint](/api/sts/) to see how agent sessions and delegation anchors participate in token exchange.

## Related Pages

- [Coordinate Agent State](/services/coordinator/)
- [Coordinate Agents](/architecture/delegation-flow/)
- [Manage Agents and Delegation](/runtime-console/agents/)