---
title: "Use API Reference"
url: "https://docs.caracal.run/v1.0/api/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/api.md"
description: "Current HTTP APIs, Gateway proxy behavior, STS exchange, Coordinator endpoints, and stream topics."
page_type: "landing"
concepts: []
requires: []
---

# Use API Reference

Canonical URL: https://docs.caracal.run/v1.0/api/
Markdown URL: https://docs.caracal.run/markdown/v1.0/api.md
Description: Current HTTP APIs, Gateway proxy behavior, STS exchange, Coordinator endpoints, and stream topics.
Page type: landing
Concepts: none
Requires: none

---

Use this section when you need wire-level behavior. For task workflows, start in [Guides](/v1.0/guides/). For service ownership and operations, use [Understand Services](/v1.0/services/) and [Operations](/v1.0/operations/).

Most integrations should use an SDK or the web console. Only the Admin API is a general external management API. Coordinator is a wire-facing SDK protocol, STS is an OAuth endpoint, Gateway is a protected reverse proxy, and event topics are deployment infrastructure rather than end-user HTTP APIs.

## API Surfaces

| Surface                                  | Base                | Purpose                                                                                                            |
| ---------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [Use the Admin API](/v1.0/api/control-plane/) | API service `/v1`   | Zones, applications, providers, resources, policies, policy sets, grants, Authority records, Sessions, audit, approvals, and templates. |
| [Use Coordinator API](/v1.0/api/coordinator/) | Coordinator service | Sessions, long-lived Session services, invocations, Delegations, and SDK lifecycle endpoints.                                   |
| [Use STS Endpoint](/v1.0/api/sts/)            | STS service         | OAuth token exchange, JWKS, Approval status, and internal policy operations.                                       |
| [Proxy Through Gateway](/v1.0/api/gateway/)   | Gateway service     | Protected reverse-proxy behavior rather than CRUD endpoints.                                                       |
| [Use Event Topics](/v1.0/api/event-topics/)   | Redis Streams       | Audit, invalidation, revocation, Session, invocation, and Delegation topics.                                       |

## Service Ports

Local Compose ports: API `3000`, Coordinator `4000`, STS `8080`, Gateway `8081`, Audit `9090`; Control shares the API port when enabled. The canonical port and endpoint maps are in [Defaults and Limits](/v1.0/reference/defaults-and-limits/#ports) and [Monitor Health and Metrics](/v1.0/operations/observability/#endpoint-map).

## Error Shape

Caracal service errors use the shared OAuth-compatible shape:

```json
{
  "error": "access_denied",
  "error_description": "policy denied request",
  "requestId": "018f..."
}
```

See [Error Codes](/v1.0/reference/errors/) for canonical codes.

Do not assume one status code across surfaces: STS follows OAuth semantics, adapters distinguish 401 from 403, and Gateway can return either a Caracal preflight error or the upstream response. Branch on the documented machine-readable `error` field where a Caracal JSON error is present.

## Stability

The public Admin `/v1` routes and STS RFC 8693 exchange are supported integration surfaces. Coordinator field names such as `agents`, `agent_session_id`, and `delegation_edge_id` are protocol names retained for SDK interoperability; applications should use facade names. `/internal/*`, operator routes, private STS directives, and raw Redis topics are not general application APIs.

## Reading Path

| Need                                      | Page                                     |
| ----------------------------------------- | ---------------------------------------- |
| Manage product objects over HTTP          | [Use the Admin API](/v1.0/api/control-plane/) |
| Manage Session and Delegation runtime state | [Use Coordinator API](/v1.0/api/coordinator/) |
| Exchange authority for mandates           | [Use STS Endpoint](/v1.0/api/sts/)            |
| Understand Gateway proxy requirements     | [Proxy Through Gateway](/v1.0/api/gateway/)   |
| Consume or verify stream contracts        | [Use Event Topics](/v1.0/api/event-topics/)   |

## Next Step

Start with [Use the Admin API](/v1.0/api/control-plane/) when automating product setup.