> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get chat history > Retrieve all events and chat metadata for the specified chat conversation. If the chat has a structured output schema, the generated structured output is returned in `chat.result`. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/chat/history openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/chat/history: get: tags: - Chat summary: Get chat history description: >- Retrieve all events and chat metadata for the specified chat conversation. If the chat has a structured output schema, the generated structured output is returned in `chat.result`. parameters: - in: query name: chatId description: Unique identifier of the chat to retrieve history for schema: type: string format: uuid description: Unique identifier of the chat to retrieve history for required: true - in: query name: limit description: Optional page size for paginated history fetch (1-100) schema: type: number minimum: 1 maximum: 100 description: Optional page size for paginated history fetch (1-100) - in: query name: beforeCursor description: Cursor for loading older events schema: type: string pattern: ^\d+:[0-9a-fA-F-]{36}$ description: Cursor for loading older events responses: '200': description: Successful response content: application/json: schema: type: object properties: events: type: array items: $ref: '#/components/schemas/ChatEvent' description: Array of chat event objects chat: oneOf: - $ref: '#/components/schemas/Chat' - type: 'null' description: Chat details or null if not found feedbackByEvent: type: object additionalProperties: type: object properties: label: type: string enum: - up - down createdAt: type: string required: - label - createdAt description: Latest human thumb feedback keyed by chat event id nextCursor: type: - string - 'null' pattern: ^\d+:[0-9a-fA-F-]{36}$ description: Cursor for loading older events hasMore: type: boolean description: Whether more older events are available required: - events - chat description: Chat history response containing events and chat metadata '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/chat/history" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ChatEvent: oneOf: - type: object properties: id: type: string description: Unique event identifier type: type: string const: chat timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to sender: type: string enum: - user - assistant description: Who sent the message messageType: type: string enum: - text - image - file - tool_result - tool_call description: Type of message content content: type: string description: Message content attachments: type: array items: type: object properties: fileId: type: string description: Unique file identifier fileName: type: string description: Original file name size: type: number description: File size in bytes objectPath: type: string description: Storage path for retrieval fileType: type: string enum: - image - pdf - spreadsheet - document - presentation - file description: Semantic file type previewText: type: string description: Optional preview text for text files required: - fileId description: Optional message attachments agentInputVersion: type: integer description: Version of structured agent input metadata agentInputSourceType: type: string description: >- Source type for structured agent input (e.g. jira_webhook, cron_trigger) agentInputSchemaType: type: string description: Human-readable schema classification for structured agent input agentInputHeadline: type: string description: Primary summary line for structured agent input agentInputContext: type: string description: Secondary context summary for structured agent input agentInputSeverity: type: string description: Severity level for structured agent input, when available agentInputLinkLabel: type: string description: >- Label for an external deep-link associated with structured agent input agentInputLinkUrl: type: string description: >- URL for an external deep-link associated with structured agent input agentInputPayload: $ref: '#/components/schemas/JsonValue' description: Normalized structured agent input payload modelAlias: description: Model used for this message toolCalls: type: array items: type: object properties: type: type: string const: tool-call toolCallId: type: string description: Unique tool call identifier toolName: type: string description: Name of the tool being called input: description: Tool arguments required: - type - toolCallId - toolName description: Tool calls made in this message required: - id - type - timestamp - chatId - sender - messageType - modelAlias - type: object properties: id: type: string description: Unique event identifier type: type: string const: liveStatus timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to text: type: string description: Status text (e.g., "Thinking", "Planning") required: - id - type - timestamp - chatId - text - type: object properties: id: type: string description: Unique event identifier type: type: string const: toolUsed timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to toolUseId: type: string description: Unique tool use identifier toolName: type: string description: Name of the tool used toolDisplayName: type: string description: Display name of the tool briefActionDescription: type: string description: Brief description of the action visibleActionInput: type: string description: Visible input to the tool status: type: string enum: - inProgress - success - error description: Tool execution status input: description: Tool input data frontendOutput: description: Tool output for frontend display rawOutputUuid: type: string description: UUID for raw output retrieval toolResultPart: description: Raw result for LLM agentChatId: type: string description: Chat ID where agent execution occurred (for agent tools) slackThread: type: object properties: teamId: type: string description: Slack workspace/team ID channelId: type: string description: Slack channel ID threadTs: type: string description: Thread timestamp (parent message ts) required: - teamId - channelId - threadTs description: >- Slack thread metadata for linking this tool call to a Slack thread required: - id - type - timestamp - chatId - toolUseId - toolName - toolDisplayName - briefActionDescription - status - type: object properties: id: type: string description: Unique event identifier type: type: string const: toolUseConfirmation timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to toolName: type: string description: Name of the tool requiring confirmation toolDescription: type: string description: Description of the tool uuid: type: string description: Confirmation UUID input: description: Tool input data toolDisplayName: type: string description: Display name of the tool briefActionDescription: type: string description: Brief description of the action required: - id - type - timestamp - chatId - toolName - toolDescription - uuid - type: object properties: id: type: string description: Unique event identifier type: type: string const: waitingForUserResponse timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to toolName: type: string description: Name of the tool that is waiting toolCallId: type: string description: The AI SDK tool call ID toolEventId: type: string description: The tool event ID for updates toolUseId: type: string description: The unique tool use ID message: type: string description: The message/question being asked buttonLabels: type: array items: type: string description: Labels for the response buttons slackChannelId: type: string description: Slack channel ID if message was sent to Slack slackMessageTs: type: string description: Slack message timestamp if message was sent to Slack promptStatus: type: string enum: - pending - resolved - cancelled description: Current status of the waiting prompt selectedLabel: type: string description: The label that was selected (when resolved) answeredBy: type: string enum: - slack - ui - timeout description: >- How the prompt was resolved: a response from Slack or the UI, or `timeout` when it elapsed with no user response (mirrors the timed-wait event's resolvedBy discriminator). slackUserId: type: string description: Slack user ID of responder if answered via Slack required: - id - type - timestamp - chatId - toolName - toolCallId - toolEventId - toolUseId - message - buttonLabels - promptStatus - type: object properties: id: type: string description: Unique event identifier type: type: string const: timedWait timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to toolName: type: string description: Name of the wait tool toolCallId: type: string description: The AI SDK tool call ID toolEventId: type: string description: The tool event ID for updates toolUseId: type: string description: The unique tool use ID waitSeconds: type: integer minimum: 60 maximum: 86400 description: Requested wait duration in seconds resumeAtTimestamp: type: number description: Unix timestamp in milliseconds when the wait should resume waitStatus: type: string enum: - pending - completed - cancelled description: Current status of the timed wait resolvedBy: type: string enum: - timer - user description: How the wait finished required: - id - type - timestamp - chatId - toolName - toolCallId - toolEventId - toolUseId - waitSeconds - resumeAtTimestamp - waitStatus - type: object properties: id: type: string description: Unique event identifier type: type: string const: statusUpdate timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to agentStatus: type: string enum: - planning - warning - executing - error - completed - idle description: Current agent status brief: type: string description: Brief status summary description: type: string description: Detailed status description planStepId: type: string description: Associated plan step ID noRender: type: boolean description: UI rendering hint required: - id - type - timestamp - chatId - agentStatus - brief - type: object properties: id: type: string description: Unique event identifier type: type: string const: structuredOutputStatus timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to status: type: string enum: - pending - generating - ready - error description: Current status of structured output generation error: type: string description: Error information when generation fails output: type: object properties: result: $ref: '#/components/schemas/JsonValue' schema: $ref: '#/components/schemas/CotoolJsonSchema' description: The structured output result and schema when ready required: - id - type - timestamp - chatId - status - type: object properties: id: type: string description: Unique event identifier type: type: string const: chatChunk timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to sender: type: string const: assistant description: Always assistant for streaming chunk: type: string description: Text chunk delta position: type: number description: Chunk position in overall content modelAlias: description: Model alias for the chunk isReasoning: type: boolean description: Whether this is a reasoning chunk required: - id - type - timestamp - chatId - sender - chunk - position - type: object properties: id: type: string description: Unique event identifier type: type: string const: reportChunk timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to position: type: number description: Chunk position in report content: type: string description: Report chunk content required: - id - type - timestamp - chatId - position - content - type: object properties: id: type: string description: Unique event identifier type: type: string const: reportComplete timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to content: type: string description: Complete report content required: - id - type - timestamp - chatId - content - type: object properties: id: type: string description: Unique event identifier type: type: string const: reportError timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to content: type: string description: Error message required: - id - type - timestamp - chatId - content - type: object properties: id: type: string description: Unique event identifier type: type: string const: artifact timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to artifactId: type: string description: Unique artifact identifier artifactType: type: string enum: - markdown-file - file - image - pdf - spreadsheet description: Type of artifact title: type: string description: Artifact title description: type: string description: Artifact description docStoreKeyStr: type: string description: Document store key for retrieval isReport: type: boolean description: Whether this is a report artifact previewText: type: string description: Content preview metadata: type: object additionalProperties: {} description: Additional metadata fileName: type: string description: Original file name if this is a file-based artifact mimeType: type: string description: MIME type for file-based artifacts size: type: number description: File size in bytes for file-based artifacts required: - id - type - timestamp - chatId - artifactId - artifactType - title - docStoreKeyStr - type: object properties: id: type: string description: Unique event identifier type: type: string const: artifactUpdate timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to artifactId: type: string description: Artifact being updated artifactType: type: string enum: - markdown-file - file - image - pdf - spreadsheet description: Type of artifact title: type: string description: Updated artifact title description: type: string description: Updated artifact description isReport: type: boolean description: Whether this is a report artifact previewText: type: string description: Updated content preview metadata: type: object additionalProperties: {} description: Updated metadata fileName: type: string description: Original file name if this is a file-based artifact mimeType: type: string description: MIME type for file-based artifacts size: type: number description: File size in bytes for file-based artifacts required: - id - type - timestamp - chatId - artifactId - artifactType - title - type: object properties: id: type: string description: Unique event identifier type: type: string const: reasoningMessage timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to sender: type: string const: assistant description: Always assistant for reasoning content: type: string description: Reasoning content modelAlias: description: Model that generated the reasoning signature: type: string description: Reasoning signature required: - id - type - timestamp - chatId - sender - content - type: object properties: id: type: string description: Unique event identifier type: type: string const: compactionStarted timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to modelAlias: description: Model alias used for compaction required: - id - type - timestamp - chatId - type: object properties: id: type: string description: Unique event identifier type: type: string const: compactionFinished timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to content: type: string description: >- Hidden compacted context payload used to reconstruct future model history modelAlias: description: Model alias that produced the compacted payload required: - id - type - timestamp - chatId - content - type: object properties: id: type: string description: Unique event identifier type: type: string const: tokenUsage timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to modelAlias: description: Model for which usage is tracked inputTokens: type: number description: Tokens used for prompt in this turn outputTokens: type: number description: Tokens used for completion in this turn totalTokens: type: number description: Total tokens used in this turn inputTokensCumulative: type: number description: Cumulative prompt tokens outputTokensCumulative: type: number description: Cumulative completion tokens totalTokensCumulative: type: number description: Cumulative total tokens loop: type: number description: Turn/loop number that produced this usage required: - id - type - timestamp - chatId - modelAlias - inputTokens - outputTokens - totalTokens - inputTokensCumulative - outputTokensCumulative - totalTokensCumulative - loop - type: object properties: id: type: string description: Unique event identifier type: type: string const: tokenUsageV2 timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to modelAlias: description: Model for which usage is tracked totalTokens: type: number description: >- The total tokens (messages + tools), prior to context management, sent to the model. This is an estimate from our context manager. contextManagedInputTokens: type: number description: >- The total input tokens (messages + tools), after context management, sent to the model. This is from the model provider. contextManagedOutputTokens: type: number description: >- The total output tokens (messages + tools), after context management, sent to the model. This is from the model provider's response. contextManagedTotalTokens: type: number description: >- The total tokens (messages + tools), after context management, sent to the model. This is from the model provider's response. loop: type: number description: Turn/loop number that produced this usage required: - id - type - timestamp - chatId - modelAlias - totalTokens - contextManagedInputTokens - contextManagedOutputTokens - contextManagedTotalTokens - loop - type: object properties: id: type: string description: Unique event identifier type: type: string const: parseError timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to content: type: string description: Error content modelAlias: description: Model alias that produced the error required: - id - type - timestamp - chatId - content - modelAlias - type: object properties: id: type: string description: Unique event identifier type: type: string const: userFileUploaded timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to fileId: type: string description: Unique file identifier fileName: type: string description: Original file name mimeType: type: string description: MIME type of the file size: type: number description: File size in bytes fileType: type: string enum: - image - pdf - spreadsheet - document - presentation - file description: Type of file objectPath: type: string description: Storage path for file retrieval previewText: type: string description: Content preview for text files metadata: type: object additionalProperties: {} description: Additional file metadata required: - id - type - timestamp - chatId - type: object properties: id: type: string description: Unique event identifier type: type: string const: chatTitleChanged timestamp: type: number description: Event timestamp chatId: type: string description: Chat ID this event belongs to title: type: string description: New chat title previousTitle: type: string description: Previous title if available required: - id - type - timestamp - chatId - title description: >- A chat event that can be one of many types: chat messages, tool usage, status updates, artifacts, etc. Each event has a discriminator field "type" that determines its structure. Chat: type: object properties: id: type: string description: Unique chat identifier userId: type: - string - 'null' description: User who owns this chat (null for agent or detection chats) agentId: type: - string - 'null' description: Agent who owns this chat (null for user or detection chats) detectionId: type: - string - 'null' description: Detection this chat belongs to (null for user or agent chats) parentChatId: type: - string - 'null' description: Parent chat for nested sub-agent chats (null for top-level chats) organizationId: type: string description: Organization this chat belongs to title: type: - string - 'null' description: Chat title createdAt: type: string description: When the chat was created format: date-time example: '2025-06-17T12:34:56.789Z' updatedAt: type: string description: When the chat was last updated format: date-time example: '2025-06-17T12:34:56.789Z' experience: type: string enum: - chat - write-detection description: The type of chat experience. Default is "chat". detectionPlatform: type: - string - 'null' enum: - panther - sublime - scanner - datadog - splunk - sentinelone - elastic - sumologic - runreveal - null description: >- The detection platform for write-detection chats (e.g., scanner, splunk, panther). Null for regular chats. modelAlias: description: >- Model alias used for this chat. Must be a valid model from the registry: anthropic:chat:sonnet-4.6, anthropic:chat:sonnet-4.5, anthropic:chat:opus-4.8, anthropic:chat:opus-4.6, anthropic:chat:opus-4.5, anthropic:chat:latest-no-reasoning, anthropic:chat:latest, anthropic:chat:opus-4.1, anthropic:chat:opus, google:chat:latest, openai:chat:gpt-5.5, openai:chat:gpt-5.4, openai:chat:gpt-5.3-codex, openai:chat:gpt-5.2-codex, openai:chat:gpt-5.2, openai:chat:gpt-5.1, openai:chat:gpt-5, openai:chat:latest, openai:chat:4o, openai:chat:o3 triggerId: type: - string - 'null' description: ID of the trigger that created this chat triggerName: type: - string - 'null' description: Name of the trigger triggerSource: type: - string - 'null' description: Source of the trigger (e.g., api, manual, jira, cron, slack) triggerDescription: type: - string - 'null' description: Description of the trigger status: type: string enum: - queued - running - waiting - done - error - interrupted description: >- Chat execution status: queued (created but not yet claimed), running (actively executing), waiting (awaiting user response), done (completed), error (failed), interrupted (stopped by user) statusMessage: type: - string - 'null' description: >- Additional status context, typically error messages for error status or waiting prompt details result: oneOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' description: Structured chat result data that matches the agent schema structuredOutputSchema: oneOf: - $ref: '#/components/schemas/CotoolJsonSchema' - type: 'null' description: The schema used to generate the structured output result shareToken: type: - string - 'null' format: uuid description: Share token for this chat (null if not shared) isPinned: type: boolean description: >- Whether the chat is pinned by its owner. Pinned chats appear in a dedicated section in the sidebar. evalScore: type: - number - 'null' description: LLM judge evaluation score (0-100) evalExplanation: type: - string - 'null' description: Explanation for the evaluation score evalBulletSummary: type: - array - 'null' items: type: string description: Bullet point summary of the evaluation criticalIssue: type: - object - 'null' properties: category: type: string enum: - authentication - connectivity - missing_data - permission - configuration - service_unavailable description: >- Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable) explanation: type: string description: One sentence explaining what went wrong required: - category - explanation description: Critical external blocker detected by LLM judge evaluation acceptanceCriteriaResults: type: - array - 'null' items: type: object properties: criterion: type: string description: The acceptance criterion being evaluated met: type: boolean description: Whether the agent run satisfied this acceptance criterion explanation: type: string description: Brief explanation of why the criterion was or was not met required: - criterion - met - explanation description: >- Per-criterion acceptance criteria evaluation results from the LLM judge required: - id - organizationId - title - createdAt - updatedAt - experience - modelAlias - status description: A chat conversation between a user/agent and the AI system ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error JsonValue: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: A JSON value (string, number, boolean, null, array, or object) CotoolJsonSchema: type: object properties: type: type: string enum: - string - number - boolean - 'null' - object - array title: type: string description: type: string properties: type: object additionalProperties: $ref: '#/components/schemas/CotoolJsonSchema' items: $ref: '#/components/schemas/CotoolJsonSchema' required: type: array items: type: string enum: type: array items: type: string additionalProperties: type: boolean x-cotool: type: object properties: presetId: type: string enum: - classification - markdown - templatedReport - toolCallEvidence viewerId: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' required: - type description: >- A JSON Schema definition with Cotool-specific extensions for structured output presets securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````