Skip to content

API Reference

All endpoints require the X-Scopebound-API-Key header.

Base URL: https://your-partner.api.scopebound.ai

POST /v1/provision

Provision a new agent session JWT for a given role.

Request

{
  "role_id": "invoice-processor",
  "framework": "langchain"
}

role_id can be either the role UUID or the role name.

Response

{
  "jwt": "eyJ...",
  "session_id": "sess-abc123",
  "expires_at": "2024-01-01T12:00:00Z"
}

POST /v1/enforce

Enforce policy on a tool call.

Request

{
  "jwt": "eyJ...",
  "tool_name": "read_invoices",
  "call_args": {"status": "pending"},
  "call_id": "optional-idempotency-key"
}

Response — allow

{
  "decision": "allow",
  "call_id": "abc123",
  "latency_ms": 1.2
}

Response — deny

{
  "decision": "deny",
  "call_id": "abc123",
  "deny_code": "SCOPE_VIOLATION",
  "severity": "medium",
  "reason": "tool not in allowed_tools",
  "retry_guidance": "check your agent role policy",
  "latency_ms": 1.1
}

Deny codes

Code Severity Meaning
SCOPE_VIOLATION medium Tool not in the role's allowed_tools list
DATA_LIMIT_EXCEEDED high Call args exceed data scope limits
SESSION_EXPIRED low JWT has expired — re-provision
RATE_LIMIT_EXCEEDED medium/high Too many calls per minute or per hour
BEHAVIORAL_DRIFT high Session behaviour flagged as anomalous
JWT_INVALID high JWT signature invalid or malformed
POLICY_ERROR high Internal policy evaluation error

POST /v1/mcp/enforce

Enforce policy on an MCP tool call. Same evaluation pipeline as /v1/enforce with MCP-native request shape.

Request

{
  "jwt": "eyJ...",
  "tool_name": "read_invoices",
  "arguments": {"status": "pending"},
  "call_id": "optional"
}

Response shape is identical to /v1/enforce.

DELETE /v1/sessions/{session_id}

Revoke an active agent session.

Response

{"revoked": true, "session_id": "sess-abc123"}

GET /mgmt/v1/roles

List all roles.

Response

[
  {
    "id": "a1b2c3d4-...",
    "name": "invoice-processor",
    "allowed_tools": ["read_invoices", "send_email"],
    "rate_limit_per_minute": 60,
    "rate_limit_per_hour": 1000,
    "default_ttl": 3600
  }
]

POST /mgmt/v1/roles

Create a new role.

Request

{
  "name": "invoice-processor",
  "description": "Invoice processing agent",
  "allowed_tools": ["read_invoices", "send_email"],
  "max_delegation_depth": 1,
  "default_ttl_seconds": 3600,
  "rate_limit_per_minute": 60,
  "rate_limit_per_hour": 1000,
  "webhook_url": "https://your-server.com/webhooks/scopebound",
  "webhook_secret": "your-hmac-secret"
}

PUT /mgmt/v1/roles/{id}

Update a role. Same request body as POST.

GET /mgmt/v1/analytics

Get usage analytics for your enforcement plane.

Query parameters

Parameter Default Max Description
window_hours 24 168 Time window in hours

Response

{
  "window_hours": 24,
  "total_calls": 1250,
  "allow_count": 1180,
  "deny_count": 70,
  "allow_rate": 0.94,
  "deny_rate": 0.06,
  "top_denied_tools": [
    {"tool_name": "delete_invoice", "deny_count": 45},
    {"tool_name": "export_data", "deny_count": 25}
  ],
  "calls_by_hour": [
    {"hour": "2024-01-01T00:00:00Z", "allow_count": 48, "deny_count": 2}
  ]
}

GET /healthz

Health check — no auth required.

Response

{
  "status": "ok",
  "sprint": "5",
  "uptime_seconds": 3600,
  "bundle_version": "1.0.0",
  "db_status": "ok"
}