Send a message to a Chat and follow the turn
Start a Chat turn with the Developer API, read its messages, and hand off to approvals when the turn pauses.
A Chat turn starts when you post a user message to an existing Chat. This guide finds the Chat, posts the message, reads the turn's output, and points to the approval flow when the turn pauses for a decision.
The Developer API has no chat-creation route. Create the Chat in the product UI first, then use the API to read and manage its messages. See Chat for how a Chat relates to its turns and Runs.
Before you start
You need:
- an existing Project Chat;
- a personal API key with the
automationmanagecapability, which also covers theautomationreadcapability every Chat read requires; - the
chat.turn.startaction grant to send a message and thechat.readaction grant to read the Chat, so the send-then-read sequence needs both; - the
projectsreadcapability to read the Project list.
Every Chat route acts as the key's issuing user, so the key must be personal: a
bot or service key is refused with 403 actor_not_available before the request
is processed.
See API keys to create a personal key, and API overview for capability levels, action grants, and the error contract.
Set the origin and key once for the examples:
export API_ORIGIN="https://api.openfactor.ai"
export API_KEY="<your API key>"Steps
1. Resolve the team, Project, and Chat
Every chat route carries teamId and projectId in its path, so resolve them
from the Project list first:
PROJECT=$(curl -sS "$API_ORIGIN/v1/projects" \
-H "Authorization: Bearer $API_KEY" |
jq -c '.projects[] | select(.slug == "my-project")')
TEAM_ID=$(printf '%s' "$PROJECT" | jq -r '.teamId')
PROJECT_ID=$(printf '%s' "$PROJECT" | jq -r '.id')Then list the Project's chats and select the one to continue:
CHATS=$(curl -sS \
"$API_ORIGIN/v1/teams/$TEAM_ID/projects/$PROJECT_ID/chats" \
-H "Authorization: Bearer $API_KEY")
CHAT_ID=$(printf '%s' "$CHATS" |
jq -r '.chats[] | select(.title == "Release checklist") | .id')The response is { chats, offset, totalCount }, newest first. Each chat carries
id, title, updatedAt, and sometimes createdAt. Pass limit and offset
to page through it.
2. Post the message
POST /v1/teams/{teamId}/projects/{projectId}/chats/{chatId}/messages
requires the automation manage capability and the chat.turn.start action
grant. The body accepts one field, text, which must be non-empty.
TURN=$(curl -sS -X POST \
"$API_ORIGIN/v1/teams/$TEAM_ID/projects/$PROJECT_ID/chats/$CHAT_ID/messages" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Summarize the open release tasks." }')
printf '%s' "$TURN" | jq .A 201 response carries the Chat id and the id of the turn it started:
{
"chatId": "chat_01",
"turnExecutionId": "turn_01"
}turnExecutionId identifies this turn; the API has no route that reads a turn
by that id. The body carries no idempotency key, so a retried request starts a
second turn. Confirm the 201 response before retrying, or read the messages
as shown next to see whether the first turn already landed.
3. Read the turn's messages
GET /v1/teams/{teamId}/projects/{projectId}/chats/{chatId}/messages returns
{ messages, offset, totalCount }. Messages are oldest first, and each one
carries id, role, and parts:
curl -sS \
"$API_ORIGIN/v1/teams/$TEAM_ID/projects/$PROJECT_ID/chats/$CHAT_ID/messages?limit=20" \
-H "Authorization: Bearer $API_KEY" |
jq '.messages[-3:]'limit accepts 1-200 and defaults to 50. offset is the index of the
first message and defaults to the latest page, so the request above returns the
newest messages without a starting index. Pass offset: 0 to read from the
beginning.
parts is a union: text and reasoning carry a text string, file carries
a mediaType and an optional filename, and tool carries the tool name,
call id, state, and bounded input and output previews. Tool payloads are
summarized because raw inputs and outputs are not a stable contract.
The assistant's reply appears as later messages. When the turn dispatches a Run, the conversation continues with that Run's result; see Workflow, Run, and Attempt for the Run lifecycle.
4. Answer an approval if the turn pauses
A turn can pause when a tool call needs a person, or when the automation policy gates an action. List the pending approvals and answer one with Answer a pending chat approval. The request ids in that response are the ones the Chat's latest turn produced, so answer before starting another turn.
Errors
The route returns a { "error": "<value>" } body. Statuses without an error
value come from the shared authentication, capability, or permission layer.
| Status | Error value | When |
|---|---|---|
401 | - | The request is missing a valid API key. |
403 | actor_not_available | The key is not a personal key that can act as a user. |
403 | - | The key lacks a capability, an action grant, or Project access. |
404 | project_not_found | The Project does not exist for the key. |
404 | chat_not_found | No Chat with that id is visible. List the Project's Chats and use a returned id. |
409 | chat_scope_conflict | The Chat's stored scope conflicts with the resolved scope. |
422 | chat_turn_rejected | The turn was rejected before it ran. |
503 | chat_storage_unavailable | Chat storage or the Chat route's configuration is unavailable. |
503 | chat_execution_unavailable | No durable worker is available to run the turn. |
A 404 deliberately does not distinguish a missing Chat from a Chat the key
may not see. The message route returns 201; the message list returns 200.
Next steps
- Answer a pending chat approval - list the approvals a turn waits on and resume it
- Chat - how a Chat relates to its turns, discussions, and Runs
- API overview - authentication, capabilities, and endpoint families
- API keys - create, scope, and revoke a key
- Command-line interface - install, authenticate, and automate the CLI