# Constellation Control Plane API

Base URL: https://api.constellationdb.dev/api/v1
OpenAPI: https://api.constellationdb.dev/openapi.json

Constellation turns immutable service revisions into audited placements on enrolled Environments. Native Next.js revisions reference framework-aware Web artifacts; generic services reference digest-pinned OCI images. The Environment agent is outbound-only; the privileged runner accepts typed, bounded operations and never arbitrary shell commands.

## Authentication

Operator endpoints currently use the signed Constellation browser session cookie. Read operations require an enabled operator account. Mutations require the platform_admin role. Agent endpoints use enrolled agent credentials and are intentionally omitted from this operator quick reference.

## Operator endpoints

- GET /products/{productSlug}/services — list logical services and head revisions
- POST /products/{productSlug}/services — create a service and immutable revision 1
- POST /products/{productSlug}/services/managed — create pinned Valkey Cache or RustFS Storage; Storage credentials are returned once
- GET /products/{productSlug}/services/{serviceName}/builds — list immutable Web builds
- POST /products/{productSlug}/services/{serviceName}/builds — build an exact Git commit into a native Web artifact, publish its revision, and queue its Environment placement
- POST /products/{productSlug}/services/{serviceName}/revisions — publish a new immutable revision
- GET /products/{productSlug}/services/{serviceName}/placements — list runtime placements
- POST /products/{productSlug}/services/{serviceName}/placements — place the current head revision on an Environment
- POST /products/{productSlug}/services/{serviceName}/placements/{placementId}/lifecycle — queue start, stop, restart, or delete
- POST or DELETE /products/{productSlug}/services/{serviceName}/placements/{placementId}/ingress — retry publication or remove managed Web ingress
- GET /products/{productSlug}/releases — list coordinated Product Releases
- POST /products/{productSlug}/releases — create an immutable coordinated release
- POST /products/{productSlug}/releases/{releaseName}/promote — point an Environment at a release

## Examples

List services with an authenticated session cookie:

```sh
curl --fail-with-body --silent --show-error \
  'https://api.constellationdb.dev/api/v1/products/constellation/services' \
  --cookie cookies.txt
```

Create a private Valkey placement from an existing managed Cache service:

```sh
curl --fail-with-body --silent --show-error \
  -X POST 'https://api.constellationdb.dev/api/v1/products/constellation/services/primary-cache/placements' \
  -H 'content-type: application/json' \
  --cookie cookies.txt \
  --data '{"environmentSlug":"primary-east"}'
```

Queue a bounded lifecycle operation:

```sh
curl --fail-with-body --silent --show-error \
  -X POST 'https://api.constellationdb.dev/api/v1/products/constellation/services/primary-cache/placements/{placementId}/lifecycle' \
  -H 'content-type: application/json' \
  --cookie cookies.txt \
  --data '{"action":"restart"}'
```

## Response contract

Successful mutations return JSON and use 201 for created resources or 202 for queued work. Errors use `{"error":{"code":"...","message":"...","requestId":"..."}}`. Keep the requestId when reporting a failed request.