All HTTP APIs are served from your Threadline deployment (by default https://api.threadline.to).
Authentication is via a Bearer API key tied to an agent.
Download the Postman collection:
threadline.postman_collection.json
Every request must include:
Authorization: Bearer tl_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/jsonKeys are created in the developer dashboard. Threadline stores a SHA-256 hash of each key and never returns the key again after creation.
If authentication fails, you'll receive:
{ "error": "Invalid API key.", "code": "UNAUTHORIZED" }GET
/api/context/[userId]
Fetch the structured context object for a user.
GET /api/context/USER_UUID
Authorization: Bearer tl_live_...{
"userId": "USER_UUID",
"communication_style": "short, direct",
"ongoing_tasks": ["Ship onboarding flow"],
"key_relationships": ["PM: Sam", "Designer: Lee"],
"domain_expertise": ["TypeScript", "product strategy"],
"preferences": { "tone": "casual", "format": "bullets" },
"emotional_state": { "recent_sentiment": "stressed but optimistic" },
"last_updated": "2026-03-12T10:00:00.000Z"
}POST
/api/context/inject
Returns a prompt string with context intelligently injected for a given user.
POST /api/context/inject
Authorization: Bearer tl_live_...
Content-Type: application/json{
"userId": "USER_UUID",
"basePrompt": "You are a helpful assistant."
}{
"injectedPrompt": "System:\nThis user prefers concise, bullet-point answers and is currently working on an onboarding flow...\n\nYou are a helpful assistant."
}POST
/api/context/update
Updates a user's context based on a single interaction.
POST /api/context/update
Authorization: Bearer tl_live_...
Content-Type: application/json{
"userId": "USER_UUID",
"userMessage": "I need to finish the onboarding flow by Friday.",
"agentResponse": "Got it. Let's break your onboarding flow into concrete steps..."
}{
"updated": true,
"delta": {
"ongoing_tasks": ["Finish onboarding flow"],
"communication_style": "short, direct"
}
}POST
/api/grants
Create a scoped grant allowing an agent to access a user's context.
{
"userId": "USER_UUID",
"agentId": "AGENT_UUID",
"scopes": ["communication_style", "ongoing_tasks"],
"expiresAt": "2026-12-31T00:00:00.000Z" // optional
}{
"grant": {
"id": "GRANT_UUID",
"user_id": "USER_UUID",
"agent_id": "AGENT_UUID",
"scopes": ["communication_style", "ongoing_tasks"],
"expires_at": "2026-12-31T00:00:00.000Z",
"revoked": false
}
}DELETE
/api/grants/[grantId]
Revoke an existing grant by ID.
{ "revoked": true }GET
/api/health
Returns basic service health information.
{ "ok": true }Threadline returns structured errors:
{ "error": "Message", "code": "ERROR_CODE" }Common codes:
| Code | HTTP | What it means / fix |
|---|---|---|
| BAD_REQUEST | 400 | Invalid params or payload. Fix your JSON/body types and required fields. |
| UNAUTHORIZED | 401 | Missing/invalid API key. Ensure Authorization: Bearer ... is set. |
| NOT_FOUND | 404 | Resource not found. Verify IDs (userId, agentId, grantId) and that the resource exists. |
| RATE_LIMITED | 429 | Too many requests. Back off and retry after X-RateLimit-Reset. |
| OPENAI_ERROR | 502 | Model integration failed. Retry, then check your OpenAI key / model availability. |
| INTERNAL_ERROR | 500 | Unexpected server error. Retry; if persistent, contact support@threadline.to. |
Threadline applies soft rate limits per API key:
If you hit a limit, you'll receive:
{ "error": "Rate limit exceeded.", "code": "RATE_LIMITED" }Enterprise and high-throughput workloads can request higher limits and dedicated capacity.