Create Project from Template

POST /api/v1/templates/{id}/project creates a new project from a template and starts an autonomous agent session. The agent executes your task without manual interaction.

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 template ID. Use the List Templates endpoint or copy the ID from a template card in the UI. The template 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 project. If omitted, Obvious generates one from the template name and a timestamp. Max 200 characters.
`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 new project, thread, and execution details.

{
  "success": true,
  "project": {
    "id": "prj_xxx",
    "name": "Q4 Sales Analysis",
    "workspaceId": "wks_xxx"
  },
  "thread": {
    "id": "th_xxx"
  },
  "execution": {
    "id": "exec_xxx",
    "status": "started"
  }
}

Field	Type	Description
`project.id`	string	The new project's ID.
`project.name`	string	The project name (your custom name or the auto-generated one).
`project.workspaceId`	string	The workspace the project belongs to.
`thread.id`	string	The conversation thread where the agent is working.
`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/templates/tpl_abc123/project \
  -H "Authorization: Bearer obv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "starterPrompt": "Analyze the uploaded CSV and create a summary report with key trends",
    "name": "Q4 Sales Analysis",
    "successPrompt": "POST the report 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`	`Template not found`	The template ID doesn't exist, isn't visible to your API key, or belongs to a different workspace.
`409`	`Thread already has an active execution`	A rare race condition. Retry the request.