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 automation manage capability, which also covers the automation read capability every Chat read requires;
  • the chat.turn.start action grant to send a message and the chat.read action grant to read the Chat, so the send-then-read sequence needs both;
  • the projects read capability 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.

StatusError valueWhen
401-The request is missing a valid API key.
403actor_not_availableThe key is not a personal key that can act as a user.
403-The key lacks a capability, an action grant, or Project access.
404project_not_foundThe Project does not exist for the key.
404chat_not_foundNo Chat with that id is visible. List the Project's Chats and use a returned id.
409chat_scope_conflictThe Chat's stored scope conflicts with the resolved scope.
422chat_turn_rejectedThe turn was rejected before it ran.
503chat_storage_unavailableChat storage or the Chat route's configuration is unavailable.
503chat_execution_unavailableNo 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