Changelog

Pagination and schema description fixes

Fixed Simple pagination on inbox tags

• GET /v1/inboxes/{inbox_id}/tags was described as returning no meta block, with next_page_url and prev_page_url in links. It does return meta. The block omits last_page and total (the endpoint does not count the full result set) and adds current_page_url. Walk the pages with links.next until it is null rather than counting them.

Changed Schema descriptions

• Error, PaginationMeta, the bearer-token bearerFormat, and the two camelCase path parameters described themselves in terms of the API's internal framework. They now describe the contract instead. No field, type, or requirement changed, so the Postman collection and the SDKs are byte-identical apart from these strings.

Response schemas verified against the live API

No endpoint, request body, scope, or authentication behaviour changed. Every documented response body was replayed against the running API and corrected where it had drifted, so the schemas now describe what the API actually returns.

Fixed Fields the docs described but the API never returns

These were removed, or renamed to the field the API really sends:

• Conversations: assignee_id and contact_id are really assignable_id / assignable_type, and snooze_until is really is_snoozed. The fields is_read and is_trashed do not exist.
• Thread events were documented as a flat message (type, body, html_body, cc_emails, ...). The API returns a nested shape: event_type, event (the message, null on system events), actor, and extra.
• Inboxes: channel, from_email, enabled, is_private, and created_at are not returned.
• Organization on GET /v1/me: name and subdomain are really company and slug.
• Tags: created_at and organization_id are not returned.
• Reports: an agent has first_name / last_name / name, not email / avatar_url. Day buckets are year / month / day, not a single date.
• Listing knowledge base articles documented a {message} stub. It returns a paginated {data, links, meta}.

Added Newly documented

• Responses now document every field the API returns, including the per-folder counts and agents/teams on an inbox, the embedded contact, last_message, and custom_field_values on a conversation, the author on a saved reply, and downloadable attachments on a message.
• GET /v1/inboxes/{inbox_id}/tags uses simple pagination: its meta has no last_page or total, and adds current_page_url.
• Free-form objects (an inbox's satisfaction-ratings config, an organization's permission matrix, a conversation's custom-field values) are documented as such rather than invented shapes.

Trimmed public surface, teammates endpoints, tag validation

Removed Dropped from the documented surface

26 operations that existed for the ThriveDesk web app rather than for integrations are no longer documented (76 operations remain). The routes themselves still exist and first-party clients are unaffected, but they are not supported for integrations and may change without notice:

• Session auth: POST /v1/auth/login and POST /v1/auth/logout. Use a personal access token instead - integrations should never collect ThriveDesk passwords.
• Composer mechanics: cancel-reply (undo send) and the saved-reply use counter.
• UI organization: custom views CRUD, custom-field reorder, and saved-reply folder rename/delete.
• Redundant bulk twins: POST /v1/settings/tags/update and /delete (use PUT/DELETE /v1/settings/tags/{tag_id}).
• Irreversible deletion: conversation force-delete and batch force-delete.
• Admin plane: automation create/update/delete (list and view remain) and Knowledge Base member/access management.
• Dashboard-only reports: recent-ratings, agent-team-conversations, agent-team-productivity.

Added New endpoints

• GET /v1/settings/users lists teammates and pending invitations; GET /v1/settings/users/{user_id} shows one teammate. Both require the users:read scope, which previously had no documented endpoint.
• POST /v1/conversation/{conversation_id}/draft creates or updates the caller's reply draft and returns the draft_id that reply and attachment upload consume. This closes the documented reply flow, which already referenced drafts without documenting how to create one.

Changed Tag validation is now enforced

• Tag create now enforces what the spec already documented: name is limited to 64 characters and color must be a 6-digit hex value (#RRGGBB). Tag merge enforces the same plus a minimum of two source tags; bulk color update requires a hex color. Previously the server accepted any string.

Fixed Schema corrections

• ReplyBody no longer documents new_conversation. The server never read it.
• The User schema now mirrors the API's user serializer: avatar (not avatar_url), full name/contact fields, presence, preferences under extra, and real role values (Account Owner, Administrator, User).
• Pagination link fields and avatar fields are typed as URIs (were mistakenly date-times) and pagination links are nullable at the edges.

Changed Tooling

• The Postman collection is now generated from the OpenAPI spec (folder per tag, schema-placeholder examples) instead of being maintained by hand, so it can no longer drift from the reference.

Accuracy pass against the API implementation

Every operation was re-verified against the API's route table, validators, and response serializers. If you coded against 1.0.0 schemas, read this list: several documented shapes did not match the running API and have been corrected to what the server actually accepts and returns.

Fixed Authentication

• The public API uses a single authentication method: a personal access token granted the first-party public scope, which can call every documented endpoint.
• POST /v1/auth/login is documented as unauthenticated.
• POST /v1/search requires a token (the auth guide previously said otherwise).

Fixed Request bodies

• Reply requires status. The message content comes from the authenticated user's draft, not the request body.
• Note uses message (not note). Forward uses body, an array to, and a required message_id. Snooze uses snoozed_until plus a required type. Split requires thread_event_id, direction, subject, and status.
• Tag attach/detach take tag. Conversation update takes assign_to/tags. Custom field values are sent as a flat key-value map.
• Batch operations: update and delete take conversations, restore and force-delete take conversation_ids. The hard flag never existed.
• Custom field and custom view create/update bodies now mirror the validators (key, is_required, structured options, filters tree, display).
• Creating a conversation requires to, status, subject, and message. Contact create persists only email. Attachment upload takes an attachments[] multipart array.
• Saved-reply folder rename/delete and GET /v1/saved-replies require inbox_id. Tag update requires name.

Fixed Responses and parameters

• Single resources are wrapped in {"data": ...}. List endpoints document their real collection shapes (paginated or plain arrays).
• Status enums corrected to Active/Pending/Closed, priority to High/Medium/Low, custom field types to text/textarea/dropdown/toggle/number.
• Date-range reports require start_date and end_date. Previously undocumented query parameters (contact search, tag search, per-page overrides, event_id, agent_id, rating, view) are now listed.
• The global rate limit (300 requests/minute per client IP) is documented in Pagination & rate limits.

Initial public release

First publication of the ThriveDesk Public API as an OpenAPI 3.1 specification. Covers the 99 endpoints documented in the previous Postman collection, plus full schema definitions, authentication scopes, error catalog, pagination contract, and rate-limit documentation.

Added Documentation

• Hand-authored OpenAPI 3.1 specification at openapi/openapi.yaml
• Bundled single-file spec at openapi/bundled.yaml
• Redoc reference renderer at reference.html
• Stoplight Elements interactive playground at playground.html
• Guides: quickstart, authentication & scopes, errors, pagination & rate limits, changelog

Fixed Crosscheck against the Postman collection

The Postman collection remains in this repository at api.postman_collection.json. The seven commits in its history (visible with git log) record the fixes applied during the crosscheck pass:

1. Fix api.conversation.merge request body - example body was invented and would have 422'd.
2. Fix api.settings.tags.merge request body - same pattern.
3. Fill empty request-body templates with real schemas - 12 endpoints had // Add request body parameters here placeholders.
4. Fix api.automations.store and api.automations.update - body used a non-existent conditions[] field and the wrong active flag.
5. Replace fabricated "string" placeholders in report responses - all 7 /v1/reports/* endpoints.
6. Replace api.search response placeholder - corrected shape.
7. Replace api.me response placeholders - corrected shape.

The Postman collection and the OpenAPI specification are intended to be kept in lockstep from here on.