The Threads API from Endgame — 2 operation(s) for threads.
openapi: 3.1.0
info:
title: Endgame Public Threads API
version: 1.0.0
description: Create and manage Endgame threads over HTTPS.
servers:
- url: https://app.endgame.io
security:
- bearerAuth: []
tags:
- name: Threads
paths:
/api/v1/threads:
post:
operationId: createThread
summary: Create a thread
description: Creates a new thread in the caller's organization. Requires a user-scoped API key; org-wide API keys and M2M applications receive `403 FORBIDDEN` during beta. The `prompt` is required -- it's persisted as the first user message and triggers the assistant's response to generate asynchronously. Poll `GET /api/v1/threads/{id}` until the derived `status.state` is `idle` (or `error`).
tags:
- Threads
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadRequest'
responses:
'200':
description: Thread created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadResponse'
'400':
$ref: '#/components/responses/InvalidParams'
'403':
$ref: '#/components/responses/Forbidden'
get:
operationId: listThreads
summary: List threads
description: Lists threads visible to the caller, ordered by most recent activity first (`updatedAt` when present, otherwise `createdAt`). Personal keys see their own threads plus every org-published thread; the org-wide principal (shared by org-wide API keys and M2M applications) sees every org-published thread.
tags:
- Threads
parameters:
- name: limit
in: query
required: false
description: Maximum number of threads to return (1-100, default 25).
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: cursor
in: query
required: false
description: Opaque cursor from a previous response's `nextCursor`. Omit for the first page.
schema:
type: string
- name: accountId
in: query
required: false
description: 'Optional filter: only return threads associated with this account ID.'
schema:
type: string
responses:
'200':
description: A page of threads.
content:
application/json:
schema:
$ref: '#/components/schemas/ListThreadsResponse'
'400':
$ref: '#/components/responses/InvalidParams'
/api/v1/threads/{id}:
get:
operationId: getThread
summary: Get a thread
description: Retrieves a thread, its messages, and its derived run status. Callers can only fetch threads they are permitted to read -- threads created by other users under a user-scoped key return `404 NOT_FOUND`.
tags:
- Threads
parameters:
- $ref: '#/components/parameters/ThreadId'
responses:
'200':
description: Thread, messages, and derived status.
content:
application/json:
schema:
$ref: '#/components/schemas/GetThreadResponse'
patch:
operationId: updateThread
summary: Update a thread
description: Renames a thread. Only `title` is writable. Requires a user-scoped API key; org-wide API keys and M2M applications receive `403 FORBIDDEN` during beta. Users can only rename threads they created -- attempts to rename another user's thread also return `403 FORBIDDEN`, even when the thread is published.
tags:
- Threads
parameters:
- $ref: '#/components/parameters/ThreadId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateThreadRequest'
responses:
'200':
description: Updated thread.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateThreadResponse'
'400':
$ref: '#/components/responses/InvalidParams'
'403':
$ref: '#/components/responses/Forbidden'
delete:
operationId: deleteThread
summary: Delete a thread
description: Soft-deletes a thread. The record is preserved server-side but will no longer appear in `GET /api/v1/threads` or be readable via `GET /api/v1/threads/{id}`. Requires a user-scoped API key; org-wide API keys and M2M applications receive `403 FORBIDDEN` during beta. Users can only delete threads they created.
tags:
- Threads
parameters:
- $ref: '#/components/parameters/ThreadId'
responses:
'200':
description: Deletion acknowledged.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteThreadResponse'
'403':
$ref: '#/components/responses/Forbidden'
components:
responses:
InvalidParams:
description: Request body or query parameters failed validation. See [Errors](/api-reference/endpoints#errors) for the full error envelope and code list.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Credential is valid but not permitted. Either the operation requires a user-scoped API key (org-wide credentials cannot mutate threads during beta), or the caller is user-scoped but did not create the thread. See [Errors](/api-reference/endpoints#errors) for the full error envelope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
DeleteThreadResponse:
type: object
required:
- id
- deleted
properties:
id:
type: string
example: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
deleted:
type: boolean
enum:
- true
description: Always `true` on a successful delete.
example: true
example:
id: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
deleted: true
ThreadStatus:
type: object
description: Derived run status based on the latest assistant message.
required:
- state
- activeMessageId
- latestUpdate
- stepCount
properties:
state:
type: string
enum:
- idle
- in_progress
- error
description: '`idle` when no assistant work is pending (or no assistant messages exist yet), `in_progress` while the assistant is still generating, `error` if the most recent assistant message failed.'
example: idle
activeMessageId:
type:
- string
- 'null'
description: ID of the assistant message currently being generated, if `state` is `in_progress`.
example: null
latestUpdate:
type:
- string
- 'null'
description: Description of the most recent reasoning step, or `"Thinking"` if the assistant hasn't emitted a step yet.
example: null
stepCount:
type: integer
minimum: 0
description: Number of reasoning steps emitted on the active assistant message.
example: 0
UpdateThreadResponse:
type: object
required:
- thread
properties:
thread:
$ref: '#/components/schemas/Thread'
ThreadMessage:
type: object
description: A single message on a thread.
required:
- id
- threadId
- role
- content
- status
- createdAt
- completedAt
- steps
- sources
- attachments
- model
properties:
id:
type: string
readOnly: true
example: msg_01HZY6P8RB4K5C7X9E2N8MDQ4U
threadId:
type: string
readOnly: true
example: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
role:
type: string
enum:
- assistant
- user
readOnly: true
example: assistant
content:
type: string
readOnly: true
example: Your team owns 42 accounts. The five largest by ARR are...
status:
type:
- string
- 'null'
enum:
- in_progress
- corroborating
- completed
- failed
- cancelled
- null
description: Lifecycle status of the message. Always `null` for `user` messages; non-null for assistant messages. `in_progress` and `corroborating` mean the assistant is still processing; `completed` is terminal success; `failed` means an error was hit; `cancelled` means the user or system aborted the message.
readOnly: true
example: completed
createdAt:
type: string
format: date-time
readOnly: true
example: '2026-04-22T14:32:11.000Z'
completedAt:
type:
- string
- 'null'
format: date-time
readOnly: true
example: '2026-04-22T14:32:18.000Z'
steps:
type:
- array
- 'null'
description: Reasoning steps emitted while the assistant was generating.
items:
type: object
required:
- description
properties:
description:
type: string
additionalProperties: true
readOnly: true
example:
- description: Looking up accounts owned by your team
- description: Ranking by annualized revenue
sources:
type:
- array
- 'null'
description: Source documents referenced by the assistant.
items:
type: object
additionalProperties: true
readOnly: true
example: null
attachments:
type:
- array
- 'null'
description: User-supplied attachments associated with the message.
items:
type: object
additionalProperties: true
readOnly: true
example: null
model:
type:
- string
- 'null'
description: Identifier of the model that produced the message, if applicable.
readOnly: true
example: claude-opus-4-7
Thread:
type: object
description: Public representation of a thread.
required:
- id
- title
- createdAt
- updatedAt
- accountId
- secondaryId
- published
- deleted
- threadUrl
properties:
id:
type: string
description: Stable thread identifier.
readOnly: true
example: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
title:
type: string
description: Human-readable title. Auto-generated from the first prompt when a thread is created without an explicit title.
example: What accounts does my team own?
createdAt:
type: string
format: date-time
description: ISO 8601 timestamp of thread creation.
readOnly: true
example: '2026-04-22T14:32:10.000Z'
updatedAt:
type:
- string
- 'null'
format: date-time
description: ISO 8601 timestamp of the last update. `null` if never updated.
readOnly: true
example: '2026-04-22T14:35:02.000Z'
accountId:
type:
- string
- 'null'
description: Associated account ID, if any.
example: 0018b00000abCdEfGhI
secondaryId:
type:
- string
- 'null'
description: Secondary linkage (e.g. opportunity, user). Settable on create only.
example: null
published:
type: boolean
description: Whether the thread is published to the organization.
readOnly: true
example: false
deleted:
type: boolean
description: Whether the thread has been soft-deleted.
readOnly: true
example: false
threadUrl:
type:
- string
- 'null'
format: uri
description: Deep link into the Endgame app for this thread.
readOnly: true
example: https://app.endgame.io/threads/thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
example:
id: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
title: What accounts does my team own?
createdAt: '2026-04-22T14:32:10.000Z'
updatedAt: '2026-04-22T14:35:02.000Z'
accountId: 0018b00000abCdEfGhI
secondaryId: null
published: false
deleted: false
threadUrl: https://app.endgame.io/threads/thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
GetThreadResponse:
type: object
required:
- thread
- messages
- status
properties:
thread:
$ref: '#/components/schemas/Thread'
messages:
type: array
items:
$ref: '#/components/schemas/ThreadMessage'
status:
$ref: '#/components/schemas/ThreadStatus'
example:
thread:
id: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
title: What accounts does my team own?
createdAt: '2026-04-22T14:32:10.000Z'
updatedAt: '2026-04-22T14:35:02.000Z'
accountId: null
secondaryId: null
published: false
deleted: false
threadUrl: https://app.endgame.io/threads/thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
messages:
- id: msg_01HZY6P8RB4K5C7X9E2N8MDQ4V
threadId: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
role: user
content: What accounts does my team own?
status: null
createdAt: '2026-04-22T14:32:10.000Z'
completedAt: null
steps: null
sources: null
attachments: null
model: null
- id: msg_01HZY6P8RB4K5C7X9E2N8MDQ4W
threadId: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
role: assistant
content: Your team owns 42 accounts. The five largest by ARR are...
status: completed
createdAt: '2026-04-22T14:32:11.000Z'
completedAt: '2026-04-22T14:32:18.000Z'
steps:
- description: Looking up accounts owned by your team
- description: Ranking by annualized revenue
sources: null
attachments: null
model: claude-opus-4-7
status:
state: idle
activeMessageId: null
latestUpdate: null
stepCount: 2
UpdateThreadRequest:
type: object
description: Only `title` is writable. Unknown fields are rejected with `INVALID_PARAMS`.
additionalProperties: false
required:
- title
properties:
title:
type: string
minLength: 1
description: New title. Must be at least one character.
example: Book of business review — Q2
example:
title: Book of business review — Q2
CreateThreadRequest:
type: object
description: Parameters for creating a thread. `prompt` is required; `title` auto-generates from it if omitted.
required:
- prompt
properties:
prompt:
type: string
minLength: 1
description: First user message on the thread. Persisted immediately and triggers an assistant response that generates asynchronously.
example: What accounts does my team own?
title:
type: string
minLength: 1
description: Explicit title. If omitted, the title is auto-generated from the prompt.
example: Book of business review
accountId:
type: string
description: Associate the thread with an account ID.
example: 0018b00000abCdEfGhI
secondaryId:
type: string
description: Secondary linkage (e.g. opportunity, user).
example: 0068b00000abCdEfGhI
example:
prompt: What accounts does my team own?
CreateThreadResponse:
type: object
required:
- thread
properties:
thread:
$ref: '#/components/schemas/Thread'
messageId:
type: string
description: ID of the user message persisted from `prompt`.
example: msg_01HZY6P8RB4K5C7X9E2N8MDQ4V
responseMessageId:
type: string
description: ID of the in-flight assistant response message. Poll `GET /api/v1/threads/{id}` until this message's `status` is `completed` or `failed`.
example: msg_01HZY6P8RB4K5C7X9E2N8MDQ4W
example:
thread:
id: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
title: What accounts does my team own?
createdAt: '2026-04-22T14:32:10.000Z'
updatedAt: null
accountId: null
secondaryId: null
published: false
deleted: false
threadUrl: null
messageId: msg_01HZY6P8RB4K5C7X9E2N8MDQ4V
responseMessageId: msg_01HZY6P8RB4K5C7X9E2N8MDQ4W
ListThreadsResponse:
type: object
required:
- threads
- nextCursor
- truncated
properties:
threads:
type: array
items:
$ref: '#/components/schemas/Thread'
nextCursor:
type:
- string
- 'null'
description: Opaque cursor for the next page. `null` when there are no more pages.
example: MjAyNi0wNC0yMlQxNDozNTowMi4wMDBafHRocl8wMUhaWTZQOFJCNEs1QzdYOUUyTjhNRFE0VA==
truncated:
type: boolean
description: '`true` when the organization has more threads than the server-side pagination window can walk. Narrow the result with `accountId` to retrieve the threads this page can''t surface.'
example: false
example:
threads:
- id: thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
title: What accounts does my team own?
createdAt: '2026-04-22T14:32:10.000Z'
updatedAt: '2026-04-22T14:35:02.000Z'
accountId: null
secondaryId: null
published: false
deleted: false
threadUrl: https://app.endgame.io/threads/thr_01HZY6P8RB4K5C7X9E2N8MDQ4T
nextCursor: null
truncated: false
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- trace_id
properties:
code:
type: string
enum:
- INVALID_PARAMS
- UNAUTHORIZED
- FORBIDDEN
- NOT_FOUND
- RATE_LIMITED
- INTERNAL_ERROR
description: Stable machine-readable error code.
example: INVALID_PARAMS
message:
type: string
description: Human-readable explanation.
example: 'prompt: String must contain at least 1 character(s)'
trace_id:
type: string
description: Unique identifier for the request. Include in support requests.
example: 01HZY6P8RB4K5C7X9E2N8MDQ4T
example:
error:
code: INVALID_PARAMS
message: 'prompt: String must contain at least 1 character(s)'
trace_id: 01HZY6P8RB4K5C7X9E2N8MDQ4T
parameters:
ThreadId:
name: id
in: path
required: true
description: Thread identifier.
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'One of: an Endgame API key prefixed `eak_` (created from Settings → API Keys with a Personal or Org-wide scope), or a WorkOS access token from an Endgame-provisioned M2M application (created from Settings → Applications and exchanged via the `client_credentials` grant).'