REST API

Reference

The REST API exposes the same operations as the MCP catalog for callers that aren’t coding agents — operational scripts, dashboard backends, CI integrations. Agents use MCP. Everything else uses REST.

Base URL

The base URL is the Greenlight install’s dashboard URL with /api/v1 appended. For an install at https://greenlight.contoso.com, the API base is https://greenlight.contoso.com/api/v1.

Authentication

Every request requires a bearer token issued by the install’s IdP through the standard OAuth flow. Three caller patterns:

Caller	Auth mechanism
Human (CLI, ad-hoc script)	Device-flow OAuth against the IdP, token cached locally.
Service principal (CI, automation)	Client-credentials OAuth against the IdP, token in env.
Inside-the-cluster service	Workload identity token, exchanged at the API edge.

Tokens carry the standard claims; Greenlight enforces RBAC by mapping IdP groups to roles as it does for the dashboard.

curl https://greenlight.contoso.com/api/v1/apps \
  -H "Authorization: Bearer $GL_TOKEN"

Pagination

List endpoints accept limit (default 50, max 200) and cursor. The response includes next_cursor if more results exist.

{
  "items": [ /* … */ ],
  "next_cursor": "eyJsYXN0X2lkIjoiYXBwX2s5eDJtM3AifQ=="
}

Pass next_cursor back as cursor on the next request. Cursors are opaque; do not parse them.

Error envelope

Every error response uses the same shape:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "User does not have role 'admin'.",
    "request_id": "req_01HQX5MWGRTYBJ7C7C7C7C7C"
  }
}

code is stable across versions; message is human-readable and may change. The HTTP status maps cleanly: 400 for input errors, 401 for missing auth, 403 for RBAC denials, 404 for missing resources, 409 for conflicts, 429 for rate limits, 5xx for platform errors.

The full code list is in Errors & pagination.

Rate limits

Per-token rate limits are configurable per organization. Default is 600 requests per minute per token, with a burst budget. When a token exceeds its limit, the API returns 429 with a Retry-After header.

Endpoints

A representative subset; the full OpenAPI spec is downloadable from the dashboard.

Apps

Method	Path	Description
GET	/apps	List apps the caller has access to.
GET	/apps/{app_id}	Get one app, including state, owner, integrations.
POST	/apps	Register a new app (same fields as MCP registerApp).
POST	/apps/{app_id}/kill	Kill an app. Body: { "reason": "…" }.
POST	/apps/{app_id}/restore	Restore a killed app.

Integrations

Method	Path	Description
GET	/integrations	List integrations.
POST	/integrations	Register a new integration.
POST	/integrations/{name}/grant	Grant an integration to one or more apps.
POST	/integrations/{name}/revoke	Revoke an integration (globally or per-app).
POST	/integrations/{name}/rotate	Rotate the credential.

Audit

Method	Path	Description
GET	/audit	Query the audit log. Supports filters and cursor pagination.
POST	/audit/export	Trigger a CSV or JSON export for a time range.

Knowledge

Method	Path	Description
GET	/knowledge	List entries.
GET	/knowledge/{id}	Get one entry.
PUT	/knowledge/{id}	Update an entry (humans only; agents use MCP propose).
GET	/knowledge/proposals	List pending proposals.
POST	/knowledge/proposals/{id}/accept	Accept a proposal.

Versioning

The API is versioned in the URL (/api/v1). Greenlight does not break a published version. New fields are additive; new endpoints are namespaced. Any future major API version will be announced with a minimum support window for v1.

Tip

For most automation, the MCP tools are the better fit — they’re identical in semantics and easier to call from an agent runtime. Use REST when you’re integrating Greenlight into a system that isn’t itself an agent.

Next

MCP tools The same operations, exposed to coding agents.

Errors & pagination The full error-code list and cursor scheme.

App environment variables The reserved variable names referenced by the API.