Docs / API

SaaS API reference you can actually use.

Everything below is production contract for /v1/*. Compatibility routes are listed at the bottom for older runtimes.

5-minute quickstart Endpoint catalog Payload templates Error contracts Adapter docs

Prereqs (set once in your shell)

export BASE_URL="http://209.46.122.136/api"
export TENANT_ID="acme"

# request access token
TOKEN_JSON=$(curl -sS -X POST "$BASE_URL/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d "{\"tenant_id\":\"$TENANT_ID\",\"subject\":\"operator\",\"scopes\":[\"integrations:read\",\"integrations:execute\"]}")

export ACCESS_TOKEN=$(echo "$TOKEN_JSON" | jq -r ".access_token // empty")
echo "ACCESS_TOKEN length: ${#ACCESS_TOKEN}"

5-minute quickstart

1. Get a token

curl -s -X POST "$BASE_URL/v1/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Token: $TENANT_TOKEN" \
  -d '{"tenant_id":"acme","subject":"operator","scopes":["integrations:read","integrations:execute"]}' | jq

2. List integrations

curl -s "$BASE_URL/v1/integrations/list?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq

3. Validate intent

curl -s -X POST "$BASE_URL/v1/integrations/validate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"adapter_id":"github","intent":{"action":"deploy_workflow_dispatch","repo":"org/repo","workflow":"deploy.yml","ref":"main","env":"staging"}}' | jq

4. Evaluate policy (example)

cat > /tmp/github_intent.json <<'JSON'
{
  "adapter_id": "github",
  "intent": {
    "action": "deploy_workflow_dispatch",
    "repo": "org/repo",
    "workflow": "deploy.yml",
    "ref": "main",
    "env": "staging"
  }
}
JSON

# Replace with your real tenant policy payload/ID
curl -sS -X POST "$BASE_URL/v1/integrations/evaluate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @/tmp/github_intent.json | jq

5. Execute dry-run

curl -sS -X POST "$BASE_URL/v1/integrations/execute" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"adapter_id":"github","intent":{"action":"deploy_workflow_dispatch","repo":"org/repo","workflow":"deploy.yml","ref":"main","env":"staging"},"dry_run":true}' | jq

Endpoint catalog

Auth

Token issue requires X-Tenant-Token header.

POST /v1/auth/token issue access + refresh token

POST /v1/auth/refresh rotate access token

POST /v1/auth/revoke revoke token chain

GET /v1/auth/introspect verify token status

Integrations

Most routes require tenant context via ?tenant_id=... or X-Tenant-Id.

GET /v1/integrations/list adapters + capabilities

GET /v1/integrations/schema/:adapter_id adapter schema

POST /v1/integrations/validate structural validation

POST /v1/integrations/evaluate decision + evidence hash

POST /v1/integrations/execute approved execution path

Policy + evidence

GET|POST /v1/policies policy documents

POST /v1/policies/:id/validate deterministic validation

POST /v1/policies/:id/simulate impact simulation

POST /v1/policies/:id/promote promotion gate

GET /v1/evidence/:evidence_hash evidence lookup

Release + post-GA

/v1/release/* finalize, closure, verification

/v1/postga/* reliability/compliance/security audits

Write operations require release-admin capability.

Rate limits apply on sensitive release operations.

Payload templates

Use adapter docs for strict per-adapter schema before sending production intents.

# /v1/integrations/validate request
{
  "adapter_id": "aws",
  "intent": {
    "action": "scale_asg",
    "region": "us-east-1",
    "account_id": "123456789012",
    "asg_name": "api-prod",
    "desired_capacity": 6,
    "environment": "prod"
  }
}

# /v1/integrations/evaluate response (shape)
{
  "approved": true,
  "deny_reason": null,
  "matched_rules": ["INFRA_ALLOW_ASG_SCALING"],
  "evidence_hash": "...",
  "evidence_packet": {"adapter_id":"aws", "decision": {...}, "normalized_action": {...}}
}

Compatibility routes (supported)

POST /adapters/http/register, /adapters/http/intent, /adapters/http/heartbeat, GET /adapters/http/runtimes

POST /openclaw/register, POST /openclaw/intent, POST /temporal/intent

GET /runtime/adapters/contracts for conformance checks

Error contracts

400 malformed request / invalid payload

403 auth/scope/capability denied

404 tenant/resource not found

409 integrity or gate failure

429 rate-limited

Fail-closed is mandatory: uncertain paths deny by default.