API quickstart

Gravitre exposes a REST API at https://gravitre.app/api. Browser sessions and API keys use the same routes; keys are required for server-to-server automation.

1. Create an API key

1. Settings → API Keys → Create key
2. Label the key (for example ci-deploy or reporting)
3. Copy the secret once — it cannot be retrieved later
4. Store in your secret manager; rotate on offboarding

See API authentication for Bearer header format and scoping notes.

2. Verify access

curl -s "https://gravitre.app/api/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

A 403 with "Organization context required" usually means the key lacks org membership — confirm the user who created the key belongs to the target org.

3. List and execute a workflow

# List workflows
curl -s "https://gravitre.app/api/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Execute (requires active version in current environment)
curl -s -X POST "https://gravitre.app/api/workflows/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "WORKFLOW_UUID",
    "parameters": {}
  }'

Response includes a run ID when execution starts or queues for approval.

4. Poll run status

curl -s "https://gravitre.app/api/runs/RUN_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

List with filters:

curl -s "https://gravitre.app/api/runs?status=failed&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

5. Connectors and sync

curl -s "https://gravitre.app/api/connectors" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -s -X POST "https://gravitre.app/api/connectors/CONNECTOR_ID/sync" \
  -H "Authorization: Bearer YOUR_API_KEY"

6. Operator action plan

curl -s -X POST "https://gravitre.app/api/operator/action-plan" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operatorGoal": "Summarize connector errors",
    "primaryContext": {"type": "connector", "id": "CONNECTOR_UUID"},
    "relatedContexts": []
  }'

7. Webhooks (outbound)

Configure under Settings → Webhooks. Gravitre POSTs signed payloads when runs complete or approvals are needed. See Webhooks.

Environment header

Many routes respect the active org environment (staging vs production). When calling from automation, pass the environment your org uses for API execution — details in OpenAPI parameter docs.

Error handling

Discover all endpoints

• Interactive: Swagger UI
• Machine-readable: openapi.json (internal admin routes redacted)

Next steps

• Monitor Runs — retry, cancel, rollback APIs
• Webhooks
• Manage settings — API keys and org security