Create Thread in Project

POST /api/v1/projects/{id}/thread creates a new thread in an existing project and starts an autonomous agent session. Use this to run additional tasks on a project without creating a new one from a template.

Authentication

Include your API key in the Authorization header of every request. API keys are scoped to a workspace and inherit the permissions of the user who created them.

Authorization: Bearer obv_your_api_key

Generate API keys in Settings → External Access.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	The project ID. The project must belong to the same workspace as your API key.

Request Body

Send a JSON object with Content-Type: application/json.

Parameter	Type	Required	Description
`starterPrompt`	string	Yes	The task you want the agent to perform. Be specific — the agent runs autonomously based on these instructions.
`name`	string	No	A name for the new thread. If omitted, defaults to `"External API Conversation"`.
`successPrompt`	string	No	Instructions the agent follows after completing the task. Use this to trigger a webhook, send a notification, or perform cleanup.
`failurePrompt`	string	No	Instructions the agent follows if it hits a blocker. Use this to notify your systems or request human review.

Response

A successful request returns 200 OK with the thread and execution details.

{
  "success": true,
  "thread": {
    "id": "th_xxx"
  },
  "execution": {
    "id": "exec_xxx",
    "status": "started"
  }
}

Field	Type	Description
`thread.id`	string	The new thread's ID.
`execution.id`	string	The agent execution ID.
`execution.status`	string	Always `"started"` on success.

Code Example

curl -X POST https://api.app.obvious.ai/api/v1/projects/prj_abc123/thread \
  -H "Authorization: Bearer obv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "starterPrompt": "Create a chart showing monthly revenue trends from the sales sheet",
    "name": "Monthly Revenue Analysis",
    "successPrompt": "POST the chart URL to https://hooks.example.com/obvious-done",
    "failurePrompt": "POST error details to https://hooks.example.com/obvious-failed"
  }'

Errors

Status	Error	Cause
`401`	`Authorization header required`	Missing `Authorization` header.
`401`	`Invalid authorization format`	Header doesn't start with `Bearer` .
`401`	`Invalid or expired API key`	The API key doesn't exist or has been revoked.
`404`	`Project not found`	The project ID doesn't exist or belongs to a different workspace.
`409`	`Thread already has an active execution`	A rare race condition. Retry the request.