---
title: "Use Management API"
url: "https://docs.caracal.run/api/control-plane/"
markdown_url: "https://docs.caracal.run/markdown/api/control-plane.md"
description: "Management API endpoints served by the Caracal API service."
page_type: "api"
concepts: []
requires: []
---

# Use Management API

Canonical URL: https://docs.caracal.run/api/control-plane/
Markdown URL: https://docs.caracal.run/markdown/api/control-plane.md
Description: Management API endpoints served by the Caracal API service.
Page type: api
Concepts: none
Requires: none

---

The Control-Plane REST API is served by the API service on port `3000`. Management routes are registered under `/v1` and are protected by admin authentication.

## Health and Diagnostics

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Liveness check. |
| `GET` | `/ready` | Dependency and service readiness. |
| `GET` | `/metrics` | Service metrics. |
| `GET` | `/docs` | Optional API docs when enabled. |

## Core Resources

| Resource | Collection | Item | Extra |
| --- | --- | --- | --- |
| Zones | `GET`, `POST /v1/zones` | `GET`, `PATCH`, `DELETE /v1/zones/:id` | `GET /v1/zones/:id/dcr-status` |
| Applications | `GET`, `POST /v1/zones/:zoneId/applications` | `GET`, `PATCH`, `DELETE /v1/zones/:zoneId/applications/:id` | `POST /v1/zones/:zoneId/applications/dcr` |
| Providers | `GET`, `POST /v1/zones/:zoneId/providers` | `GET`, `PATCH`, `DELETE /v1/zones/:zoneId/providers/:id` | — |
| Resources | `GET`, `POST /v1/zones/:zoneId/resources` | `GET`, `PATCH`, `DELETE /v1/zones/:zoneId/resources/:id` | — |

## Policy and Access

| Area | Read | Write |
| --- | --- | --- |
| Policy validation | — | `POST /v1/policies/validate` |
| Policies | `GET /v1/zones/:zoneId/policies`, `GET /v1/zones/:zoneId/policies/:id` | `POST /v1/zones/:zoneId/policies`, `POST /v1/zones/:zoneId/policies/:id/versions`, `DELETE /v1/zones/:zoneId/policies/:id` |
| Policy sets | `GET /v1/zones/:zoneId/policy-sets`, `GET /v1/zones/:zoneId/policy-sets/:id`, `GET /v1/zones/:zoneId/policy-sets/:id/versions/:versionId`, `GET /v1/zones/:zoneId/policy-sets/:id/activation-status` | `POST /v1/zones/:zoneId/policy-sets`, `POST /v1/zones/:zoneId/policy-sets/:id/versions`, `POST /v1/zones/:zoneId/policy-sets/:id/activate`, `POST /v1/zones/:zoneId/policy-sets/:id/simulate`, `DELETE /v1/zones/:zoneId/policy-sets/:id` |
| Policy templates | `GET /v1/policy-templates` | — |
| Grants | `GET /v1/zones/:zoneId/grants`, `GET /v1/zones/:zoneId/grants/:id` | `POST /v1/zones/:zoneId/grants`, `DELETE /v1/zones/:zoneId/grants/:id` |
| Provider grants | — | `POST /v1/zones/:zoneId/provider-grants`, `POST /v1/zones/:zoneId/provider-grants/oauth/authorize`, `POST /v1/zones/:zoneId/provider-grants/revoke` |

Use Console when you are performing these operations interactively. Use the Admin SDK or Control API when automation needs the same management behavior.

## Audit, Sessions, and Step-Up

| Resource | Methods and paths |
| --- | --- |
| Audit | `GET /v1/zones/:zoneId/audit`, `GET /v1/zones/:zoneId/audit/by-request/:requestId`, `GET /v1/zones/:zoneId/audit/by-request/:requestId/explain` |
| Admin audit | `GET /v1/zones/:zoneId/admin-audit` |
| Sessions | `GET /v1/zones/:zoneId/sessions` |
| Agent sessions | `GET /v1/zones/:zoneId/agent-sessions` (filter by `status`, `lifecycle`, `label`, `parent_id`, `application_id`; `format=csv` to export) |
| Step-up challenges | `GET /v1/zones/:zoneId/step-up-challenges`, `GET /v1/zones/:zoneId/step-up-challenges/:id`, `POST /v1/zones/:zoneId/step-up-challenges/:id/satisfy` |
| Zone events | Zone-scoped event routes under `/v1/zones/:zoneId/...` |

## Usage Notes

- Use Console for human workflows and Admin SDK or Control API for automation.
- For scoped, non-interactive provisioning, drive the Control API with a control key. See [Automate Management](/services/control/#non-interactive-automation) and the `controlBootstrap` example.
- Prefer declarative reconciliation over scripting individual writes: [Declarative Management](/services/control/#declarative-management) converges a zone from a desired-state document with idempotent apply, dry-run plan, and CI-friendly verify.
- Policy activation and simulation are API operations, but top-level `caracal` runtime commands do not expose them.
- Writes that produce downstream state changes enqueue signed Redis stream events through the API outbox.

## Next Step

Continue to [Use Coordinator API](/api/coordinator/) when automation needs agent session, invocation, or delegation endpoints.

## Related Pages

- [Admin Package](/sdks/admin/)
- [Manage Product Objects](/runtime-console/admin/)
- [Manage Product State](/services/api/)