> ## Documentation Index > Fetch the complete documentation index at: https://docs.inboxapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Get thread ## OpenAPI ````yaml /v2/openapi.json get /threads/{threadId} openapi: 3.1.0 info: title: Inboxapp API version: 2.0.0 description: >- The Inboxapp API gives you access to your team's conversations and the CRM state around them. Every platform uses the same resources, so your code asks what an account can do instead of which platform it is on. ## The data model ```txt Team ├── Members people on your team ├── Account links your accounts on each platform │ └── Threads one conversation with one profile │ └── Messages ├── Contacts your record of a person │ └── Profiles their account on each platform ├── Tags labels on contacts └── Statuses pipeline stages of contacts ``` | Resource | What it is | | --- | --- | | **Platform** | A messaging platform available to your team, with what it supports | | **Account link** | One of your accounts on a platform. Messages are sent from one | | **Profile** | One person's account on one platform | | **Contact** | Your team's record of a person. Groups one or more of their profiles | | **Thread** | A conversation between one account link and one profile | | **Message** | A message in a thread, which you can send, edit, unsend and react to | | **Tag** | A label on a contact. A contact can have several | | **Status** | A pipeline stage. A contact has at most one | | **Member** | A person on your team, who can be assigned threads and contacts | ## Authentication Send your API token in the `Authorization` header: `Authorization: Bearer `. The token decides the team, so no path or parameter names one. ## Profiles and contacts A **profile** holds what the platform says about a person: `username`, `displayName`, `bio`, follower counts. A **contact** holds what your team says about them: `statusId`, `tagIds`, `notes`, `valuation`, `assigneeId`. A contact groups one or more profiles. A thread is always with one profile, and its `contactId` points to the contact that profile belongs to. ```json { "id": "nq2r8v5ycx1t7m4hj6kd3wzb", "profiles": [ { "id": "n7kxqm5d9iu2sgdf6jbw4h36", "platform": "twitter", "platformId": "1876543210987654321", "username": "sarahchen", "handle": "@sarahchen", "displayName": "Sarah Chen" } ], "statusId": "r3km7xj9wq5p2bvnhfdteoly", "tagIds": ["t9wq5p2bvnhfdteolyr3km7x"], "notes": "Asked for a demo of the reporting API.", "valuation": 12000, "assigneeId": null } ``` Reads never create a contact. Someone your team has never talked to or imported has none: message them by sending to a `profile` target. ## IDs | Field | What it is | Use it for | | --- | --- | --- | | `id`, every `…Id` | An Inboxapp ID | Paths and references. Paths only take Inboxapp IDs | | `platformId` | The ID the platform gives the object: its user, conversation or message | Matching against your own data | A `platformId` always comes with a `platform`, and means nothing without it. To find a resource by its platform identity, filter its collection: ```txt GET /contacts?platform=twitter&platformId=1876543210987654321 ``` No match is an empty `data` array, never a `404`. ## Platforms and capabilities Platforms differ: one lets you edit a message, another doesn't. The API expresses that as **capabilities** instead of per-platform endpoints. `GET /platforms` lists the platforms available to your team, with their capabilities and limits. ```txt Platform capabilities the most any account on the platform can do └── Account link capabilities narrowed for this account └── Thread restrictions disabled in this conversation ``` Check both before you call: ```typescript function canEdit(accountLink: AccountLink, thread: Thread): boolean { return ( accountLink.capabilities.includes("message:edit") && !thread.restrictions.includes("message:edit") ); } ``` | Failure | Meaning | | --- | --- | | `422 capabilityNotSupported` | The account link can't do this | | `422 threadRestricted` | The platform disabled it in this conversation | | `422 mutationWindowClosed` | The platform's time window for it has passed | | `403 platformNotAvailable` | The resource is on a platform your team can't use | New platforms may be added within v2, so treat `platform` as an open string. Code that checks capabilities keeps working when they are. See [Platforms and capabilities](https://docs.inboxapp.com/v2/platforms) for what each platform supports. ## Platform data Fields every platform has are top-level. Fields only one platform has are in `platformData`, tagged by `_tag`: ```json { "platformData": { "_tag": "twitter", "encrypted": true } } ``` Ignore tags you don't know. ## Responses Every documented field is present: a value that doesn't apply is `null`. Timestamps are ISO 8601 in UTC. Within v2, fields, enum values and error codes may be added, so ignore unknown fields and handle unknown enum values. ## Pagination Collections return `{ "data": [...], "nextCursor": "..." }`. Pass `nextCursor` back as `cursor`, with the same filters, to read the next page. It is `null` on the last page. `limit` defaults to 50, up to 100. See [Pagination](https://docs.inboxapp.com/v2/reference/pagination). ## Query parameters To pass several values, repeat the key: ```txt ?accountLinkId=a&accountLinkId=b ``` Brackets (`ids[]=…`) and comma-separated values aren't accepted. See [Query parameters](https://docs.inboxapp.com/v2/reference/query-parameters). ## Expansion References are IDs by default. Use `expand` to embed the related resource next to its ID field, `contact` beside `contactId`, at most 4 per request: ```txt GET /threads?expand=contact&expand=profile ``` ## Updates In `PATCH` bodies, omitted fields are left unchanged, and `null` clears a nullable field. ## Errors Every error has the same body: ```json { "code": "capabilityNotSupported", "message": "This account can't perform this operation.", "details": { "capability": "message:edit" }, "requestId": "…" } ``` Branch on `code`, the contract. `message` can be shown to a person and may change. `details` is `null` or the object documented for that code. Share `requestId`, also in the `X-Request-Id` header, when you contact support. See [Error codes](https://docs.inboxapp.com/v2/reference/errors). ## Sending safely `POST /messages` takes an optional `Idempotency-Key` header. Retrying with the same key never sends twice: a replay returns the original result. Without a key, a retry can send twice. ## Rate limits Each team can make 300 requests per minute, 10,000 per hour and 100,000 per day. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Past a limit, requests fail with `429 rateLimited` and a `Retry-After` header. See [Rate limits](https://docs.inboxapp.com/v2/reference/rate-limits). summary: Read and act on your team's conversations across messaging platforms. servers: - url: https://inboxapp.com/api/v2 security: [] tags: - name: Platforms description: >- The messaging platforms available to the team, with what each one supports. - name: Team description: >- The team the API token belongs to, and its members: the Inboxapp users who work in it. - name: Account Links description: >- Platform accounts the team connected to Inboxapp. Every thread belongs to one, and messages are sent from one. - name: Contacts description: >- The team's record of a person, holding its CRM state: status, tags, notes, valuation and default assignee. A contact groups one or more profiles, a person's accounts on the platforms. - name: Threads description: Conversations between one of the team's account links and one profile. - name: Messages description: >- Messages in a thread, and sending, editing, unsending and reacting to them on the platform. - name: Tags description: Labels the team puts on contacts. - name: Statuses description: >- The pipeline stages a contact can be in, such as a deal stage. A contact has at most one. - name: Colors description: The colors of Inboxapp's palette, for tags and statuses. - name: Events description: >- Changes in the team, as delivered to v2 webhooks. Each event names the object that changed and carries only the values of the change; read the object for its current state. Events are kept for 7 days, up to 25,000 per team. paths: /threads/{threadId}: get: tags: - Threads summary: Get thread operationId: threads.get parameters: - name: threadId in: path schema: $ref: '#/components/schemas/Cuid2' required: true - name: expand in: query schema: type: array items: type: string enum: - profile - contact - accountLink - assignee description: >- Related resources to embed next to their ID field, one path per key, at most 4. maxItems: 4 required: false responses: '200': description: >- A conversation between one of the team's account links and one profile. content: application/json: schema: $ref: '#/components/schemas/Thread' '400': description: InvalidRequest content: application/json: schema: $ref: '#/components/schemas/InvalidRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' '403': description: PlatformNotAvailable content: application/json: schema: $ref: '#/components/schemas/PlatformNotAvailable' '404': description: ThreadNotFound content: application/json: schema: $ref: '#/components/schemas/ThreadNotFound' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimited' '500': description: Internal content: application/json: schema: $ref: '#/components/schemas/Internal' security: - bearerAuth: [] components: schemas: Cuid2: type: string pattern: ^[0-9a-z]+$ Thread: type: object properties: id: type: string platform: allOf: - $ref: '#/components/schemas/Platform' - description: Always the platform of the thread's account link and profile. platformId: anyOf: - type: string description: >- The ID the platform gives this object. Only meaningful next to its `platform`. - type: 'null' description: >- The conversation's ID on the platform. Null until the first message creates the conversation there. accountLinkId: type: string description: >- An account link: a platform account the team connected to Inboxapp, the team's side of a conversation. profileId: type: string description: 'A profile: one person''s account on one platform. Not a contact ID.' contactId: type: string description: >- A contact: the team's record of the person, with their status, tags, notes, valuation and default assignee. assigneeId: anyOf: - type: string description: 'A member: a person on the team.' - type: 'null' description: The thread's own assignee, else its contact's default. isRequest: type: boolean description: >- True while the conversation is an incoming request the account hasn't replied to or accepted. Requests are in the `requests` folder, not `inbox`. acceptanceState: type: string enum: - required - notRequired - unknown description: >- Whether the platform needs the account to accept the conversation before replying normally. `unknown` when the platform doesn't say. Independent of `isRequest`. archived: type: boolean unread: type: boolean description: >- Marked unread in Inboxapp. A thread no one has opened yet is not unread. restrictions: type: array items: type: string enum: - message:send - message:edit - message:delete:self - message:unsend - message:react - message:reply - message:forward - media:image - media:video - media:gif - media:file - media:audio - thread:typing:send - thread:typing:receive - thread:message-requests - thread:delete:remote - directory:typeahead - thread:archive:observe - thread:archive:mutate - thread:read:observe - thread:read:mutate - profile:follow - profile:unfollow description: >- Capabilities the platform disables in this conversation, on top of the account link's `capabilities`. Using one fails with `threadRestricted`. syncing: type: boolean description: >- True while Inboxapp imports the conversation's older messages, so the message list may be incomplete. typingIndicators: type: string enum: - enabled - disabled - teamDefault description: >- Whether Inboxapp sends typing indicators to the platform while someone composes in this thread. `teamDefault` follows the team's setting. lastMessage: anyOf: - $ref: '#/components/schemas/LastMessage' - type: 'null' activity: anyOf: - $ref: '#/components/schemas/ThreadActivity' - type: 'null' createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time accountLink: $ref: '#/components/schemas/AccountLink' profile: $ref: '#/components/schemas/Profile' contact: $ref: '#/components/schemas/Contact' assignee: $ref: '#/components/schemas/Member' required: - id - platform - platformId - accountLinkId - profileId - contactId - assigneeId - isRequest - acceptanceState - archived - unread - restrictions - syncing - typingIndicators - lastMessage - activity - createdAt additionalProperties: false description: A conversation between one of the team's account links and one profile. InvalidRequest: type: object properties: code: type: string enum: - invalidRequest message: type: string details: type: object properties: issues: type: array items: type: object properties: path: type: array items: anyOf: - type: string - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN message: type: string required: - path - message additionalProperties: false required: - issues additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false Unauthorized: type: object properties: code: type: string enum: - unauthorized message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false PlatformNotAvailable: type: object properties: code: type: string enum: - platformNotAvailable message: type: string details: type: object properties: platform: $ref: '#/components/schemas/Platform' required: - platform additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false ThreadNotFound: type: object properties: code: type: string enum: - threadNotFound message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false RateLimited: type: object properties: code: type: string enum: - rateLimited message: type: string details: type: object properties: window: type: string enum: - minute - hour - day limit: type: integer resetAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - window - limit - resetAt additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false Internal: type: object properties: code: type: string enum: - internal message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false Platform: type: string description: >- The platform. Every team can use twitter; a team may have others enabled. examples: - twitter LastMessage: type: object properties: id: type: string direction: type: string enum: - inbound - outbound description: >- `inbound` was received from the other side. `outbound` was sent by the account link. createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - id - direction - createdAt additionalProperties: false description: The thread's latest message. Get it for its content. ThreadActivity: type: object properties: preview: anyOf: - type: string - type: 'null' description: >- One line as the inbox shows it, such as the message text or `You reacted with 👍`. Null when there is nothing to show. direction: type: string enum: - inbound - outbound description: '`outbound` when the account link acted.' at: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - preview - direction - at additionalProperties: false description: >- The thread's latest activity: a message, or a reaction since. `at` is when it happened, which is not always the thread's position in a list: see `order`. AccountLink: type: object properties: id: type: string platform: $ref: '#/components/schemas/Platform' platformId: type: string description: >- The ID the platform gives this object. Only meaningful next to its `platform`. username: anyOf: - type: string description: >- The platform username without its display prefix. Lookups take this form. examples: - jane - type: 'null' displayName: anyOf: - type: string - type: 'null' avatarUrl: anyOf: - type: string - type: 'null' status: type: string enum: - active - offline - paused description: >- `active` sends and syncs. `paused` is stopped for the reasons in `pauseReasons`, and resumes once none remain. `offline` lost its connection to the platform and must be reconnected in Inboxapp. pauseReasons: type: array items: type: string description: Why the account link is paused. New reasons may be added. examples: - - billing - - unverified - no-xchat capabilities: type: array items: type: string enum: - message:send - message:edit - message:delete:self - message:unsend - message:react - message:reply - message:forward - media:image - media:video - media:gif - media:file - media:audio - thread:typing:send - thread:typing:receive - thread:message-requests - thread:delete:remote - directory:typeahead - thread:archive:observe - thread:archive:mutate - thread:read:observe - thread:read:mutate - profile:follow - profile:unfollow description: >- What this account can do: its platform's capabilities, narrowed for this account. An operation it lacks fails with `capabilityNotSupported`. syncedAt: anyOf: - type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time - type: 'null' description: >- When Inboxapp finished importing the account's conversations. Null until then. createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - id - platform - platformId - username - displayName - avatarUrl - status - pauseReasons - capabilities - syncedAt - createdAt additionalProperties: false description: >- A platform account the team connected to Inboxapp. Every conversation and message goes through one. Profile: type: object properties: id: type: string platform: $ref: '#/components/schemas/Platform' platformId: type: string description: >- The ID the platform gives this object. Only meaningful next to its `platform`. username: type: string description: >- The platform username without its display prefix. Lookups take this form. examples: - jane handle: type: string description: >- The username as the platform displays it. Show this, and look up by `username`. examples: - '@jane' displayName: type: string avatarUrl: anyOf: - type: string - type: 'null' bio: anyOf: - type: string - type: 'null' location: anyOf: - type: string - type: 'null' websiteUrl: anyOf: - type: string - type: 'null' websiteDomain: anyOf: - type: string - type: 'null' verified: type: boolean description: >- The platform vouches for the account, such as with an X badge. Platform-specific badges are in `platformData`. isOrganization: type: boolean description: A company or page rather than a person. isProtected: type: boolean description: The account's posts are visible only to approved followers. followerCount: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' followingCount: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' postCount: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' engagementCount: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: On X, how many posts the user has liked. listedCount: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: On X, how many lists include the profile. accountStatus: type: string enum: - active - suspended - notFound description: >- `suspended` by the platform, or `notFound` when deleted or deactivated. platformCreatedAt: anyOf: - type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time - type: 'null' description: When the account was created on the platform. profileUrl: anyOf: - type: string - type: 'null' updatedAt: type: string description: When Inboxapp last stored a change to this profile. examples: - '2026-09-14T10:32:00.000Z' format: date-time platformData: $ref: '#/components/schemas/ProfilePlatformData' required: - id - platform - platformId - username - handle - displayName - avatarUrl - bio - location - websiteUrl - websiteDomain - verified - isOrganization - isProtected - followerCount - followingCount - postCount - engagementCount - listedCount - accountStatus - platformCreatedAt - profileUrl - updatedAt - platformData additionalProperties: false description: >- One person's account on one platform. Profile data is shared across teams; the team's own data about the person is on their contact. Contact: type: object properties: id: type: string profiles: type: array items: $ref: '#/components/schemas/Profile' description: >- The person's profiles, oldest link first. Profiles on platforms unavailable to the team are left out. statusId: anyOf: - type: string description: 'A status: a pipeline stage on the team''s board.' - type: 'null' tagIds: type: array items: type: string description: 'A tag: a label the team puts on contacts.' notes: anyOf: - type: string - type: 'null' valuation: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' description: What the person is worth to the team, in the team's `currency`. assigneeId: anyOf: - type: string description: 'A member: a person on the team.' - type: 'null' description: >- The default assignee of this contact's threads that have none of their own. createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time updatedAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time status: $ref: '#/components/schemas/Status' tags: type: array items: $ref: '#/components/schemas/Tag' assignee: $ref: '#/components/schemas/Member' required: - id - profiles - statusId - tagIds - notes - valuation - assigneeId - createdAt - updatedAt additionalProperties: false description: >- The team's record of a person: their profiles, plus the team's CRM state about them. Member: type: object properties: id: type: string description: The member ID that `assigneeId` fields take. name: anyOf: - type: string - type: 'null' email: type: string imageUrl: anyOf: - type: string - type: 'null' role: type: string enum: - owner - admin - user description: >- `owner` and `admin` manage the team. A `user` can't change settings, billing or members. createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - id - name - email - imageUrl - role - createdAt additionalProperties: false description: A person on the team, who can be assigned threads and contacts. ProfilePlatformData: anyOf: - type: object properties: _tag: type: string enum: - twitter badge: anyOf: - type: string enum: - blue - gold - gray - type: 'null' profileType: type: string enum: - personal - business - government professionalCategory: anyOf: - type: string - type: 'null' urlEntities: type: array items: type: object properties: url: type: string expandedUrl: type: string displayUrl: type: string indices: type: array prefixItems: - type: number - type: number maxItems: 2 minItems: 2 required: - url - expandedUrl - displayUrl - indices additionalProperties: false bannerUrl: anyOf: - type: string - type: 'null' rawData: anyOf: - type: object - type: 'null' required: - _tag - badge - profileType - professionalCategory - urlEntities - bannerUrl - rawData additionalProperties: false - type: object properties: _tag: type: string required: - _tag description: >- A platform the team has enabled beyond those every team can use. Its fields are not listed here. description: >- Fields only one platform has, tagged by `_tag`. Ignore tags you don't know. Status: type: object properties: id: type: string name: type: string description: Unique within the team, ignoring case and accents. color: anyOf: - type: string description: A lowercase hex color. examples: - '#3b82f6' - type: 'null' description: Null when the status has no color. createdAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time required: - id - name - color - createdAt additionalProperties: false description: A pipeline stage on the team's board. A contact has at most one status. Tag: type: object properties: id: type: string name: type: string description: Unique within the team, ignoring case and accents. color: type: string description: A lowercase hex color. examples: - '#3b82f6' required: - id - name - color additionalProperties: false description: A label the team puts on contacts. A contact can have several. securitySchemes: bearerAuth: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.