HelpThread Support Inbox API — API Reference 1. Overview The HelpThread Support Inbox API lets backend engineers integrate CRM systems, customer dashboards, and internal tools with HelpThread conversations. Use it to list support conversations, reply as an agent, update ownership or status, retrieve a customer’s conversation history, and register webhook endpoints for conversation events. The API is RESTful, uses JSON request and response bodies, and is served from https://api.helpthread.com/v1. Versioning is path-based: this reference covers /v1. All requests should send Accept: application/json; requests with bodies must also send Content-Type: application/json. Authentication uses signed HMAC requests rather than bearer tokens, which helps security-conscious teams avoid transmitting long-lived secrets directly. The API design philosophy is simple: predictable resources, explicit state changes, and integration-safe defaults. Object shapes and pagination fields in this reference are inferred from the described endpoints and should be confirmed against your HelpThread workspace settings before production rollout. 2. Authentication Method: Signed-request HMAC using HMAC-SHA256 with your workspace_secret and the raw request body. Header format: Authorization: HTHMAC workspacekey="<workspacekey>", signature="sha256=<hexhmacsha256>", timestamp="<unix_timestamp>" For GET requests, sign the empty string as the request body. For POST and PATCH requests, sign the exact raw JSON string sent on the wire. Obtaining credentials: 1. Sign in to HelpThread as a workspace administrator. 2. Open Settings → Developers → API Keys. 3. Create a workspace API credential and copy the workspacekey and workspacesecret. 4. Store the workspace_secret in a server-side secrets manager. Never expose it in browsers, mobile apps, or customer-side code. 5. Restrict credential scope to only the resources your integration needs. Example request: WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY="" TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X GET "https://api.helpthread.com/v1/conversations?status=open&limit=10" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" Token lifecycle: - Expiry: HMAC credentials do not expire automatically by default; request timestamps are accepted only within a short replay window, inferred as 5 minutes — confirm for your workspace. - Rotation: Create a new credential, deploy it to all services, verify traffic, then disable the old credential. - Revocation: Revoke credentials immediately from Settings → Developers → API Keys if a secret is exposed or no longer needed. - Scope: Credentials can be scoped by workspace and permission set, inferred as conversation read/write and webhook management scopes — confirm available scopes in your account. 3. Endpoint Reference GET /conversations Description: Lists conversations in the workspace. Use status and assignee_id query filters to narrow results for CRM views, dashboards, or triage queues. Path / Query Parameters | Name | In | Type | Required | Description | |------|----|----|----------|-------------| | status | Query | string | No | Conversation status filter. Example values: open, pending, closed — inferred, confirm allowed values. | | assignee_id | Query | string | No | Filters conversations assigned to a specific HelpThread agent user ID. | | cursor | Query | string | No | Cursor returned from the previous page. | | limit | Query | integer | No | Number of records to return. Default inferred as 25; maximum inferred as 100. | Request Headers | Header | Required | Example | |--------|----------|---------| | Authorization | Yes | HTHMAC workspacekey="sktest_abc123", signature="sha256=7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4", timestamp="1715606400" | | Accept | Yes | application/json | Request Body Schema {} Success Response { "data": [ { "id": "cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A", "customerid": "cus01HXYZ2V9W8N4Q6M1B7C3D5E2F", "subject": "Unable to update billing address", "status": "open", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "created_at": "2024-05-13T14:24:00Z", "updated_at": "2024-05-13T15:02:11Z", "lastmessageat": "2024-05-13T15:02:11Z" }, { "id": "cnv_01HXYZ9C2A8B6D4F1G3H5J7K9L", "customerid": "cus01HXYZ4N6P8R2T5V7W9X1Y3Z5A", "subject": "Question about enterprise plan", "status": "open", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "created_at": "2024-05-12T09:11:42Z", "updated_at": "2024-05-13T10:18:33Z", "lastmessageat": "2024-05-13T10:18:33Z" } ], "pagination": { "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wNS0xMlQwOToxMTo0MloiLCJpZCI6ImNudl8wMUhYWVo5QzJBIn0", "has_more": true } } Error Response Example { "error": { "code": "invalid_filter", "message": "The status filter must be one of: open, pending, closed." } } Code Examples WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY="" TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X GET "https://api.helpthread.com/v1/conversations?status=open&assigneeid=usr01HXYZ7A6B5C4D3E2F1G0H9J8K&limit=25" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" import time, hmac, hashlib, requests workspacekey = "sktest_abc123" workspacesecret = b"whsectest_9d8f7a6b5c4e3d2c1b0a" body = b"" timestamp = str(int(time.time())) signature = hmac.new(workspace_secret, body, hashlib.sha256).hexdigest() headers = { "Accept": "application/json", "Authorization": f'HTHMAC workspacekey="{workspacekey}", signature="sha256={signature}", timestamp="{timestamp}"' } response = requests.get( "https://api.helpthread.com/v1/conversations", headers=headers, params={"status": "open", "limit": 25} ) print(response.json()) import crypto from "node:crypto"; const workspaceKey = "sktestabc123"; const workspaceSecret = "whsectest9d8f7a6b5c4e3d2c1b0a"; const body = ""; const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto.createHmac("sha256", workspaceSecret).update(body).digest("hex"); const response = await fetch("https://api.helpthread.com/v1/conversations?status=open&limit=25", { method: "GET", headers: { Accept: "application/json", Authorization: HTHMAC workspace_key="${workspaceKey}", signature="sha256=${signature}", timestamp="${timestamp}" } }); console.log(await response.json()); POST /conversations/:id/messages Description: Posts a reply to a conversation on behalf of an agent. Use this endpoint when an external CRM, admin console, or support dashboard needs to add an agent-visible response. Path / Query Parameters | Name | In | Type | Required | Description | |------|----|----|----------|-------------| | id | Path | string | Yes | Conversation ID. Example: cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A. | Request Headers | Header | Required | Example | |--------|----------|---------| | Authorization | Yes | HTHMAC workspacekey="sktest_abc123", signature="sha256=2c9d8a7b6e5f40392817a6b5c4d3e2f1098a7b6c5d4e3f2019283746a5b4c3d2", timestamp="1715606400" | | Content-Type | Yes | application/json | | Accept | Yes | application/json | Request Body Schema { "author_type": "agent", "agentid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "body": "Hi Jane — I updated your billing address. Please refresh your account page to confirm.", "internal": false } authortype, agentid, body, and internal are inferred fields — confirm the exact message schema for your workspace. Success Response { "data": { "id": "msg_01HXYZA4C8D6E2F9G1H3J5K7L", "conversationid": "cnv01HXYZ8N7Q4Y6V2K9M3P5T1R0A", "author_type": "agent", "agentid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "body": "Hi Jane — I updated your billing address. Please refresh your account page to confirm.", "internal": false, "created_at": "2024-05-13T15:08:42Z" } } Error Response Example { "error": { "code": "conversationnotfound", "message": "No conversation was found for id cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A." } } Code Examples WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY='{"authortype":"agent","agentid":"usr_01HXYZ7A6B5C4D3E2F1G0H9J8K","body":"Hi Jane — I updated your billing address. Please refresh your account page to confirm.","internal":false}' TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X POST "https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A/messages" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" \ -d "$BODY" import json, time, hmac, hashlib, requests workspacekey = "sktest_abc123" workspacesecret = b"whsectest_9d8f7a6b5c4e3d2c1b0a" payload = {"authortype": "agent", "agentid": "usr_01HXYZ7A6B5C4D3E2F1G0H9J8K", "body": "Hi Jane — I updated your billing address. Please refresh your account page to confirm.", "internal": False} body = json.dumps(payload, separators=(",", ":")).encode() timestamp = str(int(time.time())) signature = hmac.new(workspace_secret, body, hashlib.sha256).hexdigest() response = requests.post( "https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A/messages", headers={"Content-Type": "application/json", "Accept": "application/json", "Authorization": f'HTHMAC workspacekey="{workspacekey}", signature="sha256={signature}", timestamp="{timestamp}"'}, data=body ) print(response.json()) import crypto from "node:crypto"; const workspaceKey = "sktestabc123"; const workspaceSecret = "whsectest9d8f7a6b5c4e3d2c1b0a"; const body = JSON.stringify({ authortype: "agent", agentid: "usr_01HXYZ7A6B5C4D3E2F1G0H9J8K", body: "Hi Jane — I updated your billing address. Please refresh your account page to confirm.", internal: false }); const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto.createHmac("sha256", workspaceSecret).update(body).digest("hex"); const response = await fetch("https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A/messages", { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: HTHMAC workspace_key="${workspaceKey}", signature="sha256=${signature}", timestamp="${timestamp}" }, body }); console.log(await response.json()); PATCH /conversations/:id Description: Updates mutable conversation fields such as status and assignee. This endpoint is commonly used to sync triage decisions from a CRM or internal support queue back to HelpThread. Path / Query Parameters | Name | In | Type | Required | Description | |------|----|----|----------|-------------| | id | Path | string | Yes | Conversation ID. Example: cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A. | Request Headers | Header | Required | Example | |--------|----------|---------| | Authorization | Yes | HTHMAC workspacekey="sktest_abc123", signature="sha256=4e5f60718293a4b5c6d7e8f9012a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c", timestamp="1715606400" | | Content-Type | Yes | application/json | | Accept | Yes | application/json | Request Body Schema { "status": "pending", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K" } status and assignee_id are inferred mutable fields — confirm allowed status transitions and assignment rules. Success Response { "data": { "id": "cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A", "customerid": "cus01HXYZ2V9W8N4Q6M1B7C3D5E2F", "subject": "Unable to update billing address", "status": "pending", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "created_at": "2024-05-13T14:24:00Z", "updated_at": "2024-05-13T15:14:27Z", "lastmessageat": "2024-05-13T15:08:42Z" } } Error Response Example { "error": { "code": "invalidstatustransition", "message": "Conversation cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A cannot be moved from closed to pending." } } Code Examples WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY='{"status":"pending","assigneeid":"usr01HXYZ7A6B5C4D3E2F1G0H9J8K"}' TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X PATCH "https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" \ -d "$BODY" import json, time, hmac, hashlib, requests workspacekey = "sktest_abc123" workspacesecret = b"whsectest_9d8f7a6b5c4e3d2c1b0a" payload = {"status": "pending", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K"} body = json.dumps(payload, separators=(",", ":")).encode() timestamp = str(int(time.time())) signature = hmac.new(workspace_secret, body, hashlib.sha256).hexdigest() response = requests.patch( "https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A", headers={"Content-Type": "application/json", "Accept": "application/json", "Authorization": f'HTHMAC workspacekey="{workspacekey}", signature="sha256={signature}", timestamp="{timestamp}"'}, data=body ) print(response.json()) import crypto from "node:crypto"; const workspaceKey = "sktestabc123"; const workspaceSecret = "whsectest9d8f7a6b5c4e3d2c1b0a"; const body = JSON.stringify({ status: "pending", assigneeid: "usr01HXYZ7A6B5C4D3E2F1G0H9J8K" }); const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto.createHmac("sha256", workspaceSecret).update(body).digest("hex"); const response = await fetch("https://api.helpthread.com/v1/conversations/cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A", { method: "PATCH", headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: HTHMAC workspace_key="${workspaceKey}", signature="sha256=${signature}", timestamp="${timestamp}" }, body }); console.log(await response.json()); GET /customers/:id/conversations Description: Retrieves all conversations for a specific customer. Use this endpoint to embed support history inside a customer profile, account page, or CRM record. Path / Query Parameters | Name | In | Type | Required | Description | |------|----|----|----------|-------------| | id | Path | string | Yes | Customer ID. Example: cus_01HXYZ2V9W8N4Q6M1B7C3D5E2F. | | status | Query | string | No | Optional conversation status filter. Example values: open, pending, closed — inferred, confirm allowed values. | | cursor | Query | string | No | Cursor returned from the previous page. | | limit | Query | integer | No | Number of records to return. Default inferred as 25; maximum inferred as 100. | Request Headers | Header | Required | Example | |--------|----------|---------| | Authorization | Yes | HTHMAC workspacekey="sktest_abc123", signature="sha256=6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5", timestamp="1715606400" | | Accept | Yes | application/json | Request Body Schema {} Success Response { "data": [ { "id": "cnv_01HXYZ8N7Q4Y6V2K9M3P5T1R0A", "customerid": "cus01HXYZ2V9W8N4Q6M1B7C3D5E2F", "subject": "Unable to update billing address", "status": "pending", "assigneeid": "usr01HXYZ7A6B5C4D3E2F1G0H9J8K", "created_at": "2024-05-13T14:24:00Z", "updated_at": "2024-05-13T15:14:27Z", "lastmessageat": "2024-05-13T15:08:42Z" }, { "id": "cnv_01HXYZ5K8M2N4P6Q8R1S3T5V7W", "customerid": "cus01HXYZ2V9W8N4Q6M1B7C3D5E2F", "subject": "Login issue on mobile app", "status": "closed", "assigneeid": "usr01HXYZ1L2M3N4P5Q6R7S8T9V0W", "created_at": "2024-04-28T08:36:19Z", "updated_at": "2024-04-29T16:51:03Z", "lastmessageat": "2024-04-29T16:51:03Z" } ], "pagination": { "next_cursor": null, "has_more": false } } Error Response Example { "error": { "code": "customernotfound", "message": "No customer was found for id cus_01HXYZ2V9W8N4Q6M1B7C3D5E2F." } } Code Examples WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY="" TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X GET "https://api.helpthread.com/v1/customers/cus_01HXYZ2V9W8N4Q6M1B7C3D5E2F/conversations?limit=25" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" import time, hmac, hashlib, requests workspacekey = "sktest_abc123" workspacesecret = b"whsectest_9d8f7a6b5c4e3d2c1b0a" body = b"" timestamp = str(int(time.time())) signature = hmac.new(workspace_secret, body, hashlib.sha256).hexdigest() response = requests.get( "https://api.helpthread.com/v1/customers/cus_01HXYZ2V9W8N4Q6M1B7C3D5E2F/conversations", headers={"Accept": "application/json", "Authorization": f'HTHMAC workspacekey="{workspacekey}", signature="sha256={signature}", timestamp="{timestamp}"'}, params={"limit": 25} ) print(response.json()) import crypto from "node:crypto"; const workspaceKey = "sktestabc123"; const workspaceSecret = "whsectest9d8f7a6b5c4e3d2c1b0a"; const body = ""; const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto.createHmac("sha256", workspaceSecret).update(body).digest("hex"); const response = await fetch("https://api.helpthread.com/v1/customers/cus_01HXYZ2V9W8N4Q6M1B7C3D5E2F/conversations?limit=25", { method: "GET", headers: { Accept: "application/json", Authorization: HTHMAC workspace_key="${workspaceKey}", signature="sha256=${signature}", timestamp="${timestamp}" } }); console.log(await response.json()); POST /webhooks Description: Registers a webhook endpoint for conversation events. Webhooks are useful for keeping CRMs, data warehouses, and internal dashboards synchronized with HelpThread activity. Path / Query Parameters | Name | In | Type | Required | Description | |------|----|----|----------|-------------| | None | N/A | N/A | N/A | This endpoint does not accept path or query parameters. | Request Headers | Header | Required | Example | |--------|----------|---------| | Authorization | Yes | HTHMAC workspacekey="sktest_abc123", signature="sha256=8192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70", timestamp="1715606400" | | Content-Type | Yes | application/json | | Accept | Yes | application/json | Request Body Schema { "url": "https://crm.example.com/webhooks/helpthread", "events": [ "conversation.created", "conversation.updated", "message.created" ], "active": true } url, events, and active are inferred fields. Confirm the supported event names for your HelpThread workspace. Success Response { "data": { "id": "whk_01HXYZC8D6E4F2G9H1J3K5L7M", "url": "https://crm.example.com/webhooks/helpthread", "events": [ "conversation.created", "conversation.updated", "message.created" ], "active": true, "signingsecret": "whseclive_1a2b3c4d5e6f7g8h9i0j", "created_at": "2024-05-13T15:22:09Z" } } signing_secret in the webhook response is inferred — confirm whether HelpThread returns a webhook signing secret at creation time. Error Response Example { "error": { "code": "invalidwebhookurl", "message": "Webhook URL must be an HTTPS URL." } } Code Examples WORKSPACEKEY="sktest_abc123" WORKSPACESECRET="whsectest_9d8f7a6b5c4e3d2c1b0a" BODY='{"url":"https://crm.example.com/webhooks/helpthread","events":["conversation.created","conversation.updated","message.created"],"active":true}' TIMESTAMP="$(date +%s)" SIGNATURE="$(printf "%s" "$BODY" | openssl dgst -sha256 -hmac "$WORKSPACE_SECRET" -hex | awk '{print $2}')" curl -X POST "https://api.helpthread.com/v1/webhooks" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: HTHMAC workspacekey=\"$WORKSPACEKEY\", signature=\"sha256=$SIGNATURE\", timestamp=\"$TIMESTAMP\"" \ -d "$BODY" import json, time, hmac, hashlib, requests workspacekey = "sktest_abc123" workspacesecret = b"whsectest_9d8f7a6b5c4e3d2c1b0a" payload = {"url": "https://crm.example.com/webhooks/helpthread", "events": ["conversation.created", "conversation.updated", "message.created"], "active": True} body = json.dumps(payload, separators=(",", ":")).encode() timestamp = str(int(time.time())) signature = hmac.new(workspace_secret, body, hashlib.sha256).hexdigest() response = requests.post( "https://api.helpthread.com/v1/webhooks", headers={"Content-Type": "application/json", "Accept": "application/json", "Authorization": f'HTHMAC workspacekey="{workspacekey}", signature="sha256={signature}", timestamp="{timestamp}"'}, data=body ) print(response.json()) import crypto from "node:crypto"; const workspaceKey = "sktestabc123"; const workspaceSecret = "whsectest9d8f7a6b5c4e3d2c1b0a"; const body = JSON.stringify({ url: "https://crm.example.com/webhooks/helpthread", events: ["conversation.created", "conversation.updated", "message.created"], active: true }); const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = crypto.createHmac("sha256", workspaceSecret).update(body).digest("hex"); const response = await fetch("https://api.helpthread.com/v1/webhooks", { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: HTHMAC workspace_key="${workspaceKey}", signature="sha256=${signature}", timestamp="${timestamp}" }, body }); console.log(await response.json()); 4. Error Reference | HTTP Status | Error Code | Meaning | Suggested Resolution | |-------------|------------|---------|----------------------| | 400 | invalid_request | The request is malformed, missing required JSON, or contains unsupported fields. | Validate JSON syntax and compare the request body to the endpoint schema. | | 400 | invalid_filter | A query filter such as status has an unsupported value. | Use an allowed status value and remove unknown filters. | | 400 | invalidstatustransition | The requested conversation status change is not allowed. | Refresh the conversation state and retry with a valid transition. | | 400 | invalidwebhookurl | The webhook URL is not valid or does not use HTTPS. | Register a publicly reachable HTTPS endpoint. | | 401 | missing_authentication | The Authorization header is missing. | Include the HMAC authorization header on every request. | | 401 | invalid_signature | The HMAC signature does not match the raw request body. | Sign the exact body bytes sent in the request, including JSON formatting. | | 401 | timestampoutof_range | The request timestamp is outside the accepted replay window. | Sync server time with NTP and retry with a fresh timestamp. | | 403 | insufficient_scope | The credential is valid but lacks permission for the requested action. | Update credential scopes or use a credential with the required permissions. | | 404 | conversationnotfound | The requested conversation does not exist or is not visible to the credential. | Verify the conversation ID and workspace. | | 404 | customernotfound | The requested customer does not exist or is not visible to the credential. | Verify the customer ID and workspace. | | 409 | conflict | The resource changed while your integration was updating it. | Re-fetch the resource and retry the update if still applicable. | | 429 | ratelimitexceeded | The credential exceeded its rate limit. | Retry after X-RateLimit-Reset using exponential backoff. | 5. Rate Limits Tiers - Starter: 600 requests per minute per workspace. - Pro: 3,000 requests per minute per workspace. - Enterprise: Custom limits by contract, typically enforced per workspace and endpoint family. Limits are inferred — confirm your workspace tier in HelpThread. Response Headers - X-RateLimit-Limit: Total requests allowed in the current window. - X-RateLimit-Remaining: Requests remaining in the current window. - X-RateLimit-Reset: Unix timestamp when the current window resets. 429 Retry Strategy When you receive 429 ratelimitexceeded, pause requests until X-RateLimit-Reset if present. If the reset header is unavailable, use exponential backoff with jitter: retry after 1 second, then 2 seconds, then 4 seconds, then 8 seconds, adding a random 0–500 ms delay to avoid synchronized retries. Do not retry indefinitely; cap attempts and surface failures to your job queue or observability system. Example retry intervals: { "attempts": [ { "attempt": 1, "delay_ms": 1000 }, { "attempt": 2, "delay_ms": 2000 }, { "attempt": 3, "delay_ms": 4000 }, { "attempt": 4, "delay_ms": 8000 } ], "jitter_ms": { "min": 0, "max": 500 } } 6. Pagination Pattern: Cursor pagination. List endpoints return a pagination object with nextcursor and hasmore. Pass next_cursor as the cursor query parameter on the next request. Example — iterating all pages (in the SDK language from the inputs): import { HelpThread } from "@helpthread/node"; const client = new HelpThread({ workspaceKey: process.env.HELPTHREADWORKSPACEKEY!, workspaceSecret: process.env.HELPTHREADWORKSPACESECRET!, baseUrl: "https://api.helpthread.com/v1" }); async function listAllOpenConversations() { let cursor: string | null = null; const conversations: unknown[] = []; do { const page = await client.conversations.list({ status: "open", limit: 100, cursor: cursor ?? undefined }); conversations.push(...page.data); cursor = page.pagination.hasmore ? page.pagination.nextcursor : null; } while (cursor); return conversations; } listAllOpenConversations().then((items) => { console.log(Fetched ${items.length} open conversations); }); SDK method names are inferred — confirm against the installed @helpthread/node version. 7. SDK Quickstart (in the SDK language from the inputs) Install: npm install @helpthread/node Initialize + first call: import { HelpThread } from "@helpthread/node"; const workspaceKey = process.env.HELPTHREADWORKSPACEKEY; const workspaceSecret = process.env.HELPTHREADWORKSPACESECRET; if (!workspaceKey || !workspaceSecret) { throw new Error("Set HELPTHREADWORKSPACEKEY and HELPTHREADWORKSPACESECRET"); } const client = new HelpThread({ workspaceKey, workspaceSecret, baseUrl: "https://api.helpthread.com/v1" }); async function main() { const conversations = await client.conversations.list({ status: "open", limit: 10 }); for (const conversation of conversations.data) { console.log(${conversation.id}: ${conversation.subject}); } } main().catch((error) => { console.error(error); process.exit(1); }); SDK constructor and method names are inferred — confirm against the published package documentation. PHP integrations can use the same HMAC signing process shown in the REST examples with any standard HTTP client such as Guzzle. 8. Versioning & Changelog Policy HelpThread uses path-based API versioning. This reference documents v1 at https://api.helpthread.com/v1. Backward-compatible additions, such as new response fields or webhook event types, may be released without changing the version. Breaking changes are introduced in a new version path and announced before general availability. Deprecated fields or behaviors receive an inferred 90-day deprecation window — confirm your workspace agreement. Changelog announcements should include the affected endpoints, migration steps, and rollout dates. Sample changelog entry: { "date": "2024-06-15", "version": "v1", "type": "addition", "summary": "Added assignee_id filtering to GET /conversations.", "action_required": false }