Skip to main content
Use this flow to build conversation history into a mobile app, embedded chat, or other custom client. It takes three API calls:
  1. List the user’s conversations.
  2. Load the selected conversation’s history.
  3. 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.

​
Step 1 - List conversations

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

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:
  1. Reverse the messages array.
  2. Keep each task’s history array in its existing order.
  3. Render history entries whose role is user or agent.
  4. Read text and files from each entry’s parts array.
  5. 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:
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:
  1. task.status starts the task.
  2. Zero or more task.output.delta events carry incremental output.
  3. 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.

​
Troubleshooting

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