> ## Documentation Index > Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Conversation > The shared conversation with the Writer, Publicist or Engineer, oldest first within the newest page. Filter by task_id or page backwards with before. Unread counts belong to the token's issuer and cover the whole conversation. Reading never marks messages seen. Posting and suggestion clicks stay in the app. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/conversations/{member} openapi: 3.1.0 info: description: >- Read-only access to one organization's brands, as the member who created the API key. Each key may make 120 requests a minute. Every error is an RFC 9457 problem (`application/problem+json`) whose `code` names it. summary: Read your brands' AI visibility in Heralded. title: Heralded API version: '1' servers: - url: https://api.heralded.ai security: [] paths: /v1/brands/{brand_id}/conversations/{member}: get: tags: - v1 summary: Get Conversation description: >- The shared conversation with the Writer, Publicist or Engineer, oldest first within the newest page. Filter by task_id or page backwards with before. Unread counts belong to the token's issuer and cover the whole conversation. Reading never marks messages seen. Posting and suggestion clicks stay in the app. operationId: getConversation parameters: - in: path name: brand_id required: true schema: format: uuid title: Brand Id type: string - in: path name: member required: true schema: enum: - writer - publicist - engineer title: Member type: string - in: query name: task_id required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Task Id - in: query name: before required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Before - in: query name: limit required: false schema: default: 50 maximum: 100 minimum: 1 title: Limit type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Conversation' description: Successful Response '400': content: application/problem+json: example: code: invalid_cursor detail: The cursor is invalid or belongs to a different query. instance: example-request-id status: 400 title: Bad Request type: about:blank schema: $ref: '#/components/schemas/Problem' description: The cursor is invalid or belongs to a different query. '401': content: application/problem+json: example: code: invalid_token detail: >- The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired. instance: example-request-id status: 401 title: Unauthorized type: about:blank schema: $ref: '#/components/schemas/Problem' description: No API key, or one that is unknown, revoked or expired. headers: WWW-Authenticate: schema: example: Bearer type: string '404': content: application/problem+json: example: code: not_found detail: Nothing here that this API key can read. instance: example-request-id status: 404 title: Not Found type: about:blank schema: $ref: '#/components/schemas/Problem' description: No such brand or answer, or the key's owner cannot read it. '409': content: application/problem+json: example: code: workspace_archived detail: The API key's organization is archived. instance: example-request-id status: 409 title: Conflict type: about:blank schema: $ref: '#/components/schemas/Problem' description: The API key's organization is archived. '422': content: application/problem+json: example: code: invalid_request detail: The request's parameters are invalid; `errors` names each one. errors: - loc: - query - limit msg: Input should be less than or equal to 100 type: less_than_equal instance: example-request-id status: 422 title: Unprocessable Content type: about:blank schema: $ref: '#/components/schemas/ValidationProblem' description: A path or query parameter is invalid. '429': content: application/problem+json: example: code: rate_limited detail: >- This caller is past its requests for the minute. Retry after the seconds in Retry-After. instance: example-request-id rate_limit: limit: 120 remaining: 0 reset: 60 window: 60 status: 429 title: Too Many Requests type: about:blank schema: $ref: '#/components/schemas/RateLimitProblem' description: The API key made more than 120 requests in the minute. headers: Retry-After: description: Seconds until the key may call again. schema: example: 60 type: integer security: - apiKey: [] components: schemas: V1Conversation: properties: has_older: title: Has Older type: boolean mentioned_unread: title: Mentioned Unread type: integer messages: items: $ref: '#/components/schemas/V1ConversationMessage' title: Messages type: array unread: title: Unread type: integer required: - messages - unread - mentioned_unread - has_older title: V1Conversation type: object Problem: description: |- An RFC 9457 problem. `type` is always `about:blank`, so `title` is the status's name, and `code` is what a client branches on. properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance title: Problem type: object ValidationProblem: properties: code: title: Code type: string detail: title: Detail type: string errors: items: $ref: '#/components/schemas/ValidationIssue' title: Errors type: array instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - errors title: ValidationProblem type: object RateLimitProblem: properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string rate_limit: $ref: '#/components/schemas/RateLimitValues' status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - rate_limit title: RateLimitProblem type: object V1ConversationMessage: properties: answer_status: anyOf: - type: string - type: 'null' title: Answer Status author: title: Author type: string body: title: Body type: string created_at: format: date-time title: Created At type: string id: format: uuid title: Id type: string kind: enum: - person - member - event - step title: Kind type: string member: enum: - writer - publicist - engineer title: Member type: string mentions: items: format: uuid type: string title: Mentions type: array proposals: description: Proposals without a task. Confirm and Not now stay in the app. items: $ref: '#/components/schemas/V1ConversationProposal' title: Proposals type: array reply_to: anyOf: - $ref: '#/components/schemas/V1ConversationQuote' - type: 'null' suggestions: items: $ref: '#/components/schemas/V1ConversationSuggestion' title: Suggestions type: array task_id: anyOf: - format: uuid type: string - type: 'null' title: Task Id task_title: anyOf: - type: string - type: 'null' title: Task Title required: - id - member - author - kind - body - task_id - task_title - reply_to - suggestions - proposals - mentions - answer_status - created_at title: V1ConversationMessage type: object ValidationIssue: properties: loc: items: anyOf: - type: string - type: integer title: Loc type: array msg: title: Msg type: string type: title: Type type: string required: - loc - msg - type title: ValidationIssue type: object RateLimitValues: properties: limit: title: Limit type: integer remaining: title: Remaining type: integer reset: title: Reset type: integer window: title: Window type: integer required: - limit - window - remaining - reset title: RateLimitValues type: object V1ConversationProposal: properties: arguments: additionalProperties: true title: Arguments type: object clicked_at: anyOf: - format: date-time type: string - type: 'null' title: Clicked At clicked_by: anyOf: - format: uuid type: string - type: 'null' title: Clicked By content_piece_id: anyOf: - format: uuid type: string - type: 'null' title: Content Piece Id draft_id: anyOf: - type: string - type: 'null' title: Draft Id expected_state: anyOf: - type: string - type: 'null' title: Expected State hidden_at: anyOf: - format: date-time type: string - type: 'null' title: Hidden At id: format: uuid title: Id type: string kind: description: >- Suggestion kind. New kinds may be added; handle unknown values gracefully. title: Kind type: string x-extensible-enum: - start - not_now - schedule - request_changes - place_top - track_prompt - pause_prompt - add_competitor - remove_competitor - file_correction - file_page_fix - order_content label: title: Label type: string note: anyOf: - type: string - type: 'null' title: Note object: anyOf: - type: string - type: 'null' title: Object result: anyOf: - additionalProperties: true type: object - type: 'null' title: Result scheduled_for: anyOf: - format: date type: string - type: 'null' title: Scheduled For task_id: anyOf: - format: uuid type: string - type: 'null' title: Task Id uses: items: type: string title: Uses type: array version: anyOf: - type: integer - type: 'null' title: Version required: - id - kind - label - task_id - expected_state - object - uses - arguments - result - hidden_at - scheduled_for - note - version - content_piece_id - draft_id - clicked_by - clicked_at title: V1ConversationProposal type: object V1ConversationQuote: properties: author: title: Author type: string body: title: Body type: string id: format: uuid title: Id type: string required: - id - author - body title: V1ConversationQuote type: object V1ConversationSuggestion: properties: arguments: additionalProperties: true title: Arguments type: object clicked_at: anyOf: - format: date-time type: string - type: 'null' title: Clicked At clicked_by: anyOf: - format: uuid type: string - type: 'null' title: Clicked By content_piece_id: anyOf: - format: uuid type: string - type: 'null' title: Content Piece Id draft_id: anyOf: - type: string - type: 'null' title: Draft Id expected_state: title: Expected State type: string hidden_at: anyOf: - format: date-time type: string - type: 'null' title: Hidden At id: format: uuid title: Id type: string kind: description: >- Suggestion kind. New kinds may be added; handle unknown values gracefully. title: Kind type: string x-extensible-enum: - start - not_now - schedule - request_changes - place_top - track_prompt - pause_prompt - add_competitor - remove_competitor - file_correction - file_page_fix - order_content label: title: Label type: string note: anyOf: - type: string - type: 'null' title: Note object: anyOf: - type: string - type: 'null' title: Object result: anyOf: - additionalProperties: true type: object - type: 'null' title: Result scheduled_for: anyOf: - format: date type: string - type: 'null' title: Scheduled For task_id: format: uuid title: Task Id type: string uses: items: type: string title: Uses type: array version: anyOf: - type: integer - type: 'null' title: Version required: - id - kind - label - task_id - expected_state - object - uses - arguments - result - hidden_at - scheduled_for - note - version - content_piece_id - draft_id - clicked_by - clicked_at title: V1ConversationSuggestion type: object securitySchemes: apiKey: description: 'An API key, sent as `Authorization: Bearer hrld_...`.' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.