Manage agent conversations via API

Use this flow to build conversation history into a mobile app, embedded chat, or other custom client. It takes three API calls:

List the user’s conversations.
Load the selected conversation’s history.
Send the next message with the same contextId.

For complete request and response schemas, use the linked API reference pages.

Prerequisites

An Agent Creator agent ID (agent_<uuid>). An administrator can provide it, or you can copy it from the agent’s URL.
A user-bound JWT or access token sent as Authorization: Bearer <token>. See Authentication.
Read access to the agent.

Examples use api.studio.prisme.ai. For sandbox, use api.sandbox.prisme.ai. For self-hosted deployments, use your instance’s API host.

BASE="https://api.studio.prisme.ai/v2/workspaces/slug:agent-factory/webhooks"
AGENT_ID="agent_<uuid>"
TOKEN="YOUR_ACCESS_TOKEN"

Step 1 - List conversations

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/v1/agents/$AGENT_ID/conversations?page=1&limit=20"

The response contains conversation metadata, not message content. Keep the contextId of the conversation the user selects. Conversations are scoped to the user represented by the token. If the same application calls this endpoint with another user’s token, that user gets a different list. See List conversations for an agent for filters, pagination, and the response schema.

Step 2 - Load the history

CONTEXT_ID="ctx_..."

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE/v1/agents/$AGENT_ID/conversations/$CONTEXT_ID?page=1&limit=100"

The response has two fields:

conversation contains the thread metadata.
messages contains the conversation turns as A2A task records.

The API returns tasks from newest to oldest. To render a chronological chat:

Reverse the messages array.
Keep each task’s history array in its existing order.
Render history entries whose role is user or agent.
Read text and files from each entry’s parts array.
If your client uses the OpenAI naming convention, map agent to assistant.

History entries without a role are execution activities, such as tool calls. You can omit them from a basic chat transcript. Page 2 contains older turns, so prepend those turns when implementing “load earlier messages.” See Get a conversation with its message history for the complete response schema.

Step 3 - Continue the conversation

Send the next message with the selected conversation’s contextId:

curl -N -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -X POST "$BASE/v1/agents/$AGENT_ID/messages/stream" \
  -d "{\"message\":{\"contextId\":\"$CONTEXT_ID\",\"parts\":[{\"text\":\"Can you clarify?\"}]}}"

The server reloads the history associated with that contextId before running the agent. Omit contextId to start a new conversation, then store the contextId returned by the first task.status event. The stream follows this sequence:

task.status starts the task.
Zero or more task.output.delta events carry incremental output.
task.output.completed ends the lifecycle sequence.

On task.output.completed, inspect data.status.state. Treat failed as an error and input-required as a paused task that needs a user response or approval, not as an empty successful response. Each frame is a data: <json> line; the server emits no native SSE event: field. Lifecycle frames use {"event": "<name>", "data": {...}}. Frames without an event property are transport frames: discard only {"keepAlive": true}. The server closes the stream with a summary frame shaped as {"error": ..., "task": {"status": {"state": ...}}}. Inspect it: an early authorization failure is delivered there, with its code in error.error and HTTP 200 already committed. Never treat HTTP 200 alone as success. See Stream an agent reply via SSE for the request schema and stream contract.

Optional - Send a message that survives a retry

A mobile client can lose the response to a send: the app is killed, or the network drops before the reply arrives. Retrying the same request would run the agent twice and, without a contextId, open a second conversation. To make the retry safe, send through messages/send with an idempotency key.

Mint a key before the first attempt

Generate a key once per logical message, for example a UUID stored with the queued message, and keep it for every retry of that message. The key is 1 to 128 characters of A-Z, a-z, 0-9, ., _, : and -.

Upload attachments, if any

Read the upload target from the agent instead of hardcoding a workspace:

UPLOAD_URL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "$BASE/v1/agents/$AGENT_ID" | jq -r '.attachments.upload.url')

curl -s -H "Authorization: Bearer $TOKEN" \
  -F "file=@report.pdf" -F "public=false" \
  "$UPLOAD_URL"

The response is an array of files. Put each file’s url in a part of the message, for example {"url": "<url>", "filename": "report.pdf", "mediaType": "application/pdf"}.

Send with the key

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$BASE/v1/agents/$AGENT_ID/messages/send" \
  -d "{\"message\":{\"metadata\":{\"clientMessageId\":\"$MESSAGE_KEY\"},\"parts\":[{\"text\":\"Summarize the attached report.\"}]}}"

Send the exact same request again if you did not receive the response.

How the server answers a retry with the same key:

Situation	Response
The first send finished	The first response, unchanged, with `task.replayed: true`. The agent does not run again.
The first send is still running	`409 MESSAGE_IN_PROGRESS`, with `details.contextId` and `details.retryAfter` in seconds.
The first send never finished (after 15 minutes by default)	A `failed` task with `task.replayed: true`. `task.id` is absent when no task was created.

Keep these rules in mind:

The key alone identifies the message. The server does not compare the body of a retry with the first one, so a different message sent under a used key gets the first answer. Mint a new key for every new message.
Retries count against the rate limits. A retry over the limit gets 429, not the stored answer.
The key needs a user identity. With an organization API key that has no user behind it, the server ignores the key and sends the message normally.
Keys are kept for 7 days by default. After that, the same key is treated as a new message.
messages/stream does not support the key.

See Send a message to an agent for the request schema and every response.

Troubleshooting

Symptom	What to check
`401 UNAUTHORIZED`	The Bearer token is present and has not expired.
`403 FORBIDDEN`	The token’s user can read the agent. For organization-scoped access, call `GET /v2/me` and verify that `orgSlugs` contains the agent’s organization.
The conversation list is empty	The conversations were created by the same user represented by the token.
`404 CONVERSATION_NOT_FOUND`	The `agentId`, `contextId`, and authenticated user identify the same conversation.
The history appears reversed	Reverse `messages`, but do not reverse each task’s `history`.
The streamed response appears empty	Inspect the summary frame: handle `error.error` when present; otherwise read `task.status.state`.
`409 MESSAGE_IN_PROGRESS`	The first send with this `clientMessageId` is still running. Wait `details.retryAfter` seconds, or open `details.contextId`.
A retry returns an unrelated answer	The `clientMessageId` was reused for a different message. Mint a new key per message.
`400 VALIDATION_ERROR` on `clientMessageId`	The key is longer than 128 characters or contains a character outside `A-Za-z0-9._:-`.

The Conversations API reference also documents creating, renaming, starring, archiving, and deleting conversations.

Adoption & Governance

Use cases

DSUL

Templates

Tutorials

Security & Compliance

Support

Manage agent conversations via API

Prerequisites

Step 1 - List conversations

Step 2 - Load the history

Step 3 - Continue the conversation

Optional - Send a message that survives a retry

Troubleshooting

​Prerequisites

​Step 1 - List conversations

​Step 2 - Load the history

​Step 3 - Continue the conversation

​Optional - Send a message that survives a retry

​Troubleshooting

​Related API operations

Prerequisites

Step 1 - List conversations

Step 2 - Load the history

Step 3 - Continue the conversation

Optional - Send a message that survives a retry

Troubleshooting

Related API operations