Turn (low-level) - Gradient

Turn runs one turn of a published agent and hands the full transcript back to you. Unlike invoke, which starts fresh and returns only the reply, turn is built for callers that keep conversation state themselves and replay it on each request.

POST https://api.usegradient.dev/v1/turn

When to use which

Use	For
Invoke	A one-shot call. The engine drives the graph to completion for your message and returns the reply.
Turn	A multi-turn conversation you drive. You send the running transcript and the next message; the engine returns the updated transcript for you to store and send back next time.

The console’s own conversation chat uses this route under the hood. For most integrations, invoke is enough; reach for turn when you need to inspect or persist the transcript between turns.

Request

Header: Authorization: Bearer $GRADIENT_API_KEY. The key needs the agents:invoke scope.
Header: content-type: application/json.
Body: a JSON object.

Field	Type	Required	Description
`agentId`	string	yes	The agent UUID.
`nodeVersion`	integer	yes	A published version, `1` or greater. An API key cannot target `draft` on this route.
`message`	string	yes	The new user message for this turn.
`messages`	array	no	The transcript so far. Omit or pass `[]` on the first turn; on later turns pass the `messages` array from the previous response.
`currentNodeKey`	string	no	The node to resume on. Omit on the first turn to start at the entrypoint; on later turns pass the value from the previous response.
`variables`	object	no	String key/value state seeded into the conversation and substituted as `{{key}}` in prompts. Echoed back in the response.
`drive`	boolean	no	When `true`, auto-continue the graph until it ends or waits, instead of stopping after one model turn. Defaults to `false`.
`kickoff`	boolean	no	When `true`, allow an empty `message` to start the session at the entrypoint.

Each entry in messages has this shape:

{
  "role": "assistant",
  "content": "Can I get your date of birth?",
  "nodeKey": "patient_lookup",
  "nodeVersion": 1
}

Example

curl -X POST https://api.usegradient.dev/v1/turn \
  -H "authorization: Bearer $GRADIENT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "agentId": "<agent-uuid>",
    "nodeVersion": 1,
    "message": "I need to book a follow-up",
    "messages": []
  }'

{
  "reply": "Happy to help. Can I get your date of birth?",
  "messages": [
    { "role": "user", "content": "I need to book a follow-up" },
    { "role": "assistant", "content": "Happy to help. Can I get your date of birth?", "nodeKey": "triage", "nodeVersion": 1 }
  ],
  "currentNodeKey": "triage",
  "nodeVersion": 1,
  "ended": false,
  "agentId": "<agent-uuid>",
  "traceRunId": "<trace-run-id>",
  "variables": {}
}

Response

Field	Type	Description
`reply`	string	The agent’s assistant text for this turn.
`messages`	array	The full updated transcript. Send it back as `messages` on the next turn.
`currentNodeKey`	string	The node the conversation is now on. Send it back as `currentNodeKey`.
`nodeVersion`	integer	The running published version.
`ended`	boolean	`true` once the agent has called `end_call`.
`agentId`	string	The agent UUID.
`traceRunId`	string	The trace run recorded for this turn.
`variables`	object	The conversation’s variable state after the turn.

When the graph is parked on a timed wait, the response also carries waiting: true, a waitUntil timestamp, and any waitConfig.

Continuing a conversation

To take the next turn, send a request with the messages, currentNodeKey, and nodeVersion from the previous response, plus the new message. Keep the same agentId and nodeVersion for the life of the conversation.

Errors

Status	Meaning
`400`	`message` is missing without `kickoff`, or `agentId` or a published `nodeVersion` is missing
`401`	Missing or invalid key, or the key lacks `agents:invoke`
`402`	Billing blocks the request