Jump go di content

API reference guide

Reference for WorkItem operation dem, decision-step control, integration execution and telemetry export.

We design dis API dem for automation behaviour wey you fit predict, with policy and tenant scoping wey clear.

Base endpoint wey you go use

Use di public API endpoint wey you configure for authenticated request dem.

https://api.threada.ai

Authentication plus context

  • Use scoped credential dem for API access
  • Put tenant and role context wia dem require am
  • Request wey no get valid context dey fail closed

Scope dem wey people dey use

  • workitems:read plus workitems:write
  • workflow:manage for policy and decision update dem
  • actions:execute for execution wey governance dey guard
  • telemetry:read for export and analysis

Pagination plus filtering

  • List endpoint dem dey support pagination wey use cursor abi token
  • Filter by channel, workflow, status, policy version and time range
  • For big telemetry export, use window wey get boundary

Error model

  • Typed error category dem for validation, authorization, policy and execution failure
  • Reason code dem dey make operator tool fit handle am di same way every time
  • Dem dey return Correlation ID dem make you fit investigate across service

Example request dem

Create WorkItem from intake payload

Create canonical work record for workflow processing. Put di channel identifier for di intake channel wia dem require am.

Request 
curl -X POST "https://api.threada.ai/api/v1/public/work-items" \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"subject\":\"Review renewal request\",\"channel\":\"web\",\"channel_id\":\"web_main\",\"initial_message\":{\"role\":\"user\",\"content\":\"Review this renewal request before approval\"},\"tags\":[\"policy_review\"]}"
Response 
{
  "work_item": {
    "summary": {
      "work_item_id": "wi_123",
      "status": "new",
      "subject": "Review renewal request"
    }
  }
}

Run action wey dem don approve

Run action wey policy don approve against integration wey you configure.

Request 
curl -X POST "https://api.threada.ai/api/v1/public/work-items/wi_123/actions" \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"integration_id\":\"int_workflow\",\"idempotency_key\":\"act_456\",\"payload\":{\"type\":\"custom_http\",\"method\":\"POST\",\"url\":\"https://api.example.com/approvals\",\"body_json\":\"{\\\"approved\\\":true}\"}}"
Response 
{
  "action": {
    "action_id": "act_456",
    "work_item_id": "wi_123",
    "action_type": "custom_http",
    "status": "completed"
  }
}

Sample artifact dem

Example dem wey dey show di object dem wey Threada dey produce, with synthetic data — no be real customer abi real record. Field name dem dey follow Threada API and audit schema dem.

You need guidance to implement am?

Use di docs and technical overview for rollout and governance pattern dem.

Contact di technical team