Agentic DevelopmentThreads

Start a session

Start an agent session in a thread. The session runs in the thread's project. You need write access to the thread: you own it, or it is shared as writable. The session is recorded only. Nothing starts the agent yet.

POST
/v1/threads/{threadId}/sessions
AuthorizationBearer <token>

API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.

In: header

Path Parameters

threadId*string

Thread ULID

Header Parameters

Idempotency-Key?string

Optional retry-safety key, valid for 12 hours. Send the same key to retry a create safely: within that window you get the session the first request created, answered with 200 instead of 201. Reusing a key with a different thread or body is rejected with 422. After 12 hours the key is forgotten and the same value starts a new session.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

prompt*string

The first message to the agent

Match^[^\x00-\x08\x0b\x0c\x0e-\x1f\x7f]*$
Length1 <= length <= 32768

Response Body

application/json

application/problem+json

curl -X POST "https://example.com/v1/threads/string/sessions" \  -H "Content-Type: application/json" \  -d '{    "prompt": "string"  }'
{  "archived_at": "string",  "created_at": "string",  "id": "string",  "last_turn_ended_at": "string",  "project": {    "id": "string",    "name": "string",    "org": "string"  },  "thread_id": "string"}