> ## Documentation Index > Fetch the complete documentation index at: https://docs.custral.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a conversation > Fetch one conversation with its transcript (`messages`) and `participants`. **Requires scope:** `conversations:read`. ## OpenAPI ````yaml /openapi-v1.json get /v1/conversations/{id} openapi: 3.1.0 info: title: Custral API version: v1 description: >- The curated, versioned, API-key-authenticated public REST surface (`/v1`). Every endpoint here is what the official SDKs (`@custral/sdk`) and the MCP server are built on. Authenticate with a secret API key (`sk_…`) created in **Settings → Applications**. contact: name: Custral Support email: hello@custral.com url: https://custral.com license: name: Proprietary url: https://custral.com servers: - url: https://api.custral.com description: Production security: - ApiKey: [] tags: - name: Identity description: Introspect the calling API key. - name: Records description: Create, list, retrieve, and update records on any object. - name: Objects description: Read the object (table) schema of your workspace. - name: Conversations description: View, manage, and ingest conversations and their messages. - name: MCP description: Introspect the Model Context Protocol tool surface for a key. - name: Documents description: Read record notes / page documents as markdown. paths: /v1/conversations/{id}: get: tags: - Conversations summary: Retrieve a conversation description: >- Fetch one conversation with its transcript (`messages`) and `participants`. **Requires scope:** `conversations:read`. operationId: getConversation parameters: - name: id in: path required: true description: The conversation id (`conv_…`). schema: type: string example: conv_123 responses: '200': description: The conversation. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Conversation' reqId: $ref: '#/components/schemas/RequestId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: Conversation: type: object description: >- A conversation. `messages` + `participants` are present on retrieve/create and absent from list rows. properties: id: type: string example: conv_123 title: type: - string - 'null' example: Jane Doe status: type: - string - 'null' example: open outcome: type: - string - 'null' description: A disposition key, or null. example: won summary: type: - string - 'null' sourceType: type: - string - 'null' example: imessage channelId: type: - string - 'null' example: chan_123 startedAt: type: - string - 'null' format: date-time endedAt: type: - string - 'null' format: date-time createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time messages: type: array items: $ref: '#/components/schemas/Message' participants: type: array items: $ref: '#/components/schemas/Participant' required: - id RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 Message: type: object description: A single transcript message. properties: id: type: string example: msg_123 text: type: string example: On my way! author: type: - string - 'null' description: Display name of the sender. example: Jane Doe authorId: type: - string - 'null' description: Stable handle of the sender (phone, email, record id). example: '+15551234567' sourceType: type: - string - 'null' example: imessage direction: type: - string - 'null' enum: - inbound - outbound - null example: inbound timestamp: type: - string - 'null' format: date-time required: - id - text Participant: type: object description: A conversation participant — a linked record or a guest. properties: type: type: - string - 'null' enum: - record - guest - user - null example: record name: type: - string - 'null' example: Jane Doe email: type: - string - 'null' example: jane@acme.com recordId: type: - string - 'null' description: Set only for a linked record. example: rec_123 Error: type: object description: >- The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request. properties: error: type: object properties: code: type: string example: insufficient_scope required: - code reqId: $ref: '#/components/schemas/RequestId' required: - error responses: Unauthorized: description: >- The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key reqId: req_2a1f9c8e7b6d5 Forbidden: description: >- The key lacks the scope this endpoint requires (`code: insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope reqId: req_2a1f9c8e7b6d5 NotFound: description: 'The object or record was not found (`code: not_found`).' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found reqId: req_2a1f9c8e7b6d5 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: sk_... description: >- A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser. ```` ## Related topics - [Retrieve an object](/api-reference/objects/retrieve-an-object.md) - [Retrieve a record](/api-reference/records/retrieve-a-record.md) - [Retrieve a document](/api-reference/documents/retrieve-a-document.md) - [Retrieve a usage module](/api-reference/usage-modules/retrieve-a-usage-module.md) - [Retrieve an auto-fill agent](/api-reference/property-agents/retrieve-an-auto-fill-agent.md)