---
title: "Manage Product State"
url: "https://docs.caracal.run/services/api/"
markdown_url: "https://docs.caracal.run/markdown/services/api.md"
description: "Service reference for the Caracal API service."
page_type: "reference"
concepts: []
requires: []
---

# Manage Product State

Canonical URL: https://docs.caracal.run/services/api/
Markdown URL: https://docs.caracal.run/markdown/services/api.md
Description: Service reference for the Caracal API service.
Page type: reference
Concepts: none
Requires: none

---

The API service owns product-management state and route handlers for zones, applications, providers, resources, policies, policy sets, grants, step-up challenges, policy templates, and zone events.

## Runtime

| Property | Value |
| --- | --- |
| Port | `3000` |
| Health | `GET /health` |
| Readiness | `GET /ready` |
| Metrics | `GET /metrics` |
| Main route prefix | `/v1` |
| Optional docs route | `/docs` when API docs are enabled |

## Dependencies

| Dependency | Purpose |
| --- | --- |
| Postgres | Product state, admin tokens, policy versions, grants, sessions, outbox, audit admin events. |
| Redis | Event streams and outbox dispatch. |
| STS | Service URL used by management flows that need STS coordination. |
| Runtime secrets | Admin token, zone KEK, stream HMAC, audit HMAC, Gateway-STS HMAC, database and Redis URLs. |

## Event Output

API writes `event_outbox` rows in the same transaction as product-state changes. The dispatcher signs payloads with `STREAMS_HMAC_KEY` and publishes Redis stream events such as policy invalidation and audit records.

## Operational Signals

| Signal | Meaning |
| --- | --- |
| API readiness | Database, Redis, outbox dead rows, and service config are healthy enough for management operations. |
| `API_READY_OUTBOX_DEAD_MAX` | Readiness threshold for dead outbox rows. |
| Admin auth failures | Token, scope, or rate-limit issue for Console/Admin clients. |
| Outbox age/dead metrics | Redis or dispatcher is not draining management events. |

## Next Step

Use [Coordinate Agent State](/services/coordinator/) to understand agent sessions, invocations, and delegation runtime state.

## Related Pages

- [Use Management API](/api/control-plane/)
- [Manage Product Objects](/runtime-console/admin/)
- [Operate PostgreSQL](/operations/postgres/)