Request Conventions

URL Structure

Most integration operations are tenant/workspace scoped:

/api/v1/tenants/{tenant_id}/workspaces/{workspace_id}/{resource}

Do not hardcode IDs. Resolve context dynamically (for example via default-context endpoint).

Headers

Common headers:

• Authorization: Bearer <token> for JWT mode.
• X-API-Key: <raw_key> for API key mode.
• Content-Type: application/json for JSON bodies.

Context headers are available when path params are absent:

• X-Tenant-ID
• X-Workspace-ID

If both header and path values are present, they must match.

Pagination

Common query fields:

• page (default 1)
• page_size (default 20, max 100)

Typical paginated response shape:

{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 20,
  "pages": 0
}

Sorting and Filtering

Where supported, endpoints accept:

• sort_by
• sort_order (asc or desc)
• resource-specific filters like status, search, IDs

Success Wrapper Patterns

Two common response styles:

• Resource or paginated object directly.
• Standard success wrapper:

{
  "success": true,
  "message": "Operation completed",
  "data": {}
}

Be prepared to parse both patterns by endpoint contract.