Skip to content
Ghaymah Ghaymah Ghaymah Docs

REST API overview

The Ghaymah REST API gives you programmatic access to every resource: apps, S3 buckets and keys, volumes, managed PostgreSQL, and secrets. It’s the same API the CLI and dashboard use under the hood.

Base URL

Section titled “Base URL”
https://api.cumin.dev

All paths in this reference are relative to that base URL. Set the base URL from the API_URL environment variable when using an SDK, or hard-code it in your own client.

Authentication

Section titled “Authentication”

Every request is authenticated with a bearer token:

Authorization: Bearer <token>

Tokens are scoped to one or more projects via an OPA policy, so a token can only touch the resources it’s allowed to.

Getting a token

Section titled “Getting a token”
Terminal window
# 1. Create a project (admin scope) — returns an id and an initial token
curl -X POST https://api.cumin.dev/projects \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-project" }'
# { "id": "…", "token": "…" }


# 2. (Optional) mint an additional scoped token for a project
curl -X POST https://api.cumin.dev/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-token", "policy": "<opa-policy>" }'
# { "bearer_token": "…", "token": { "id": "…", … } }

Use the returned token for all subsequent requests.

Project scoping

Section titled “Project scoping”

Most resources belong to a project. Scope a request to a project with either:

  • the X-Cumin-Project-ID header:

    X-Cumin-Project-ID: <project-id>

  • or a project_id field in the request body:

    { "project_id": "…", "name": "my-app" }

Create and update endpoints accept both; list endpoints return only the resources the token can see.

Response conventions

Section titled “Response conventions”
Pattern Behavior
POST /resource Creates a resource; returns { "id": "…" } (or more)
GET /resource Lists resources visible to the token
PUT /resource Updates a resource; the body must include its id
DELETE /resource/{id} Deletes a single resource by id

Errors return a non-2xx status with a JSON or text body describing what went wrong. The Go and Python SDKs surface these as typed errors.

Resource types

Section titled “Resource types”

The platform recognizes these resource types (used in token policies):

app  bucket  key  secret  constellation  volume  postgres
Resource Endpoint Page
Apps /apps Apps API
S3 buckets /s3/buckets S3 API
S3 keys /s3/keys S3 API
Volumes /volumes Volumes API
PostgreSQL /db/postgres PostgreSQL API
Secrets /secrets Secrets API
Pull secrets /secrets/pull Secrets API

Health check

Section titled “Health check”
Terminal window
curl https://api.cumin.dev/health

Returns 200 when the API is up. Useful for monitoring and connectivity tests.

SDKs

Section titled “SDKs”

Official SDKs wrap these endpoints with typed clients:

  • Python — cumin_sdk (CuminClient)
  • Go — internal/cumin client in the Ghaymah codebase

Both follow the same endpoint shapes documented here.

Next steps

Section titled “Next steps”