Skip to content

API reference

Reference for WorkItem operations, decision-step controls, integration execution, and telemetry export.

These APIs are designed for predictable automation behavior with explicit policy and tenant scoping.

Base endpoint

Use your configured public API endpoint for authenticated requests.

https://api.threada.ai

Authentication and context

  • Use scoped credentials for API access
  • Include tenant and role context where required
  • Requests without valid context fail closed

Typical scopes

  • workitems:read and workitems:write
  • workflow:manage for policy and decision updates
  • actions:execute for governed execution
  • telemetry:read for exports and analysis

Pagination and filtering

  • List endpoints support cursor- or token-based pagination
  • Filter by channel, workflow, status, policy version, and time range
  • Prefer bounded windows for large telemetry exports

Error model

  • Typed error categories for validation, authorization, policy, and execution failures
  • Reason codes support deterministic handling in operator tooling
  • Correlation IDs are returned for cross-service investigation

Example requests

Create a WorkItem from intake payload

Create a canonical work record for workflow processing. Include the channel identifier for the intake channel when required.

Request 
curl -X POST "https://api.threada.ai/work-items" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{\"workflow_id\":\"policy_review\",\"channel_id\":\"web_main\",\"payload\":{\"message\":\"Review this renewal request before approval\"}}"
Response 
{
  "work_item_id": "wi_123",
  "status": "new",
  "workflow_id": "policy_review"
}

Execute an approved action

Run a policy-approved action against a configured integration.

Request 
curl -X POST "https://api.threada.ai/actions/execute" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{\"work_item_id\":\"wi_123\",\"action_id\":\"request_approval\",\"integration_id\":\"int_workflow\"}"
Response 
{
  "execution_id": "ex_456",
  "status": "started",
  "idempotency_key": "idem_789"
}

Need implementation guidance?

Use the docs and technical overview for rollout and governance patterns.

Contact technical team