{"openapi":"3.1.0","info":{"title":"TruCom REST API","version":"1.0.0","description":"Build a branded support experience with scoped server access to customers, tickets, customer replies, feature requests, conversations and signed widget identity."},"servers":[{"url":"https:\/\/trucom.app\/api\/v1\/rest"}],"security":[{"bearerAuth":[]}],"paths":{"\/me":{"get":{"operationId":"getApiContext","summary":"Check API access","description":"Return the workspace, widget, granted scopes and key expiry. Any valid API key can call this endpoint.","tags":["Authentication"],"security":[{"bearerAuth":[]}],"x-required-scope":null,"parameters":[],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ApiContextResponse"}}}}}}},"\/customers":{"get":{"operationId":"listCustomers","summary":"List customers","description":"Return active customer profiles in creation order. Merged profiles are excluded. List responses omit widget_context.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:read","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerListResponse"}}}}}},"post":{"operationId":"createCustomer","summary":"Create a customer","description":"Create a profile with at least one of name, email, phone or external_id. Identities must not already belong to another customer. An Idempotency-Key is required.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"description":"Unique operation key. Same method, path and JSON content replays for 24 hours by default. Different content returns 409. Rotation clears replay history."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerWrite"}}}}},"put":{"operationId":"upsertCustomer","summary":"Create or update by external ID","description":"external_id is required and must be non-empty. Create a profile if this normalized external ID is new, otherwise update the existing profile. Omitted fields stay unchanged. A conflicting email or phone returns 422; profiles are never merged implicitly.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"description":"Unique operation key. Same method, path and JSON content replays for 24 hours by default. Different content returns 409. Rotation clears replay history."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}},"200":{"description":"Existing customer updated","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerUpsert"}}}}}},"\/customers\/lookup":{"get":{"operationId":"lookupCustomer","summary":"Look up a customer","description":"Provide exactly one of email, phone or external_id. Matching uses TruCom identity normalization; it is exact, not fuzzy. External IDs are trimmed, whitespace-normalized and case-insensitive. Phone values remove formatting and preserve international + prefixes.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:read","parameters":[{"name":"email","in":"query","schema":{"type":"string"},"description":"Exact email identity. Supply only one lookup field."},{"name":"phone","in":"query","schema":{"type":"string"},"description":"Exact phone identity. Supply only one lookup field."},{"name":"external_id","in":"query","schema":{"type":"string"},"description":"Exact external_id identity. Supply only one lookup field."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}}}}},"\/customers\/{customer}":{"get":{"operationId":"getCustomer","summary":"Get a customer","description":"Return a customer profile with canonical attributes and up to five recent website attribute snapshots.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:read","parameters":[{"name":"customer","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26},"description":"Public ULID of a resource in the key\u2019s workspace."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}}}},"patch":{"operationId":"updateCustomer","summary":"Update a customer","description":"Update only supplied fields. Nullable profile fields clear their current values. Attributes merge by key; a null attribute removes the key. Identity conflicts return 422.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"customers:write","parameters":[{"name":"customer","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26},"description":"Public ULID of a resource in the key\u2019s workspace."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$"},"description":"Unique operation key. Same method, path and JSON content replays for 24 hours by default. Different content returns 409. Rotation clears replay history."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CustomerWrite"}}}}}},"\/customers\/{customer}\/conversations":{"get":{"operationId":"listCustomerConversations","summary":"List a customer\u2019s conversations","description":"Read conversations for this customer in the current workspace.","tags":["Customers"],"security":[{"bearerAuth":[]}],"x-required-scope":"conversations:read","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"customer","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26},"description":"Public ULID of a resource in the key\u2019s workspace."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversationListResponse"}}}}}}},"\/conversations":{"get":{"operationId":"listConversations","summary":"List conversations","description":"Read conversation summaries in creation order. Filter by a customer public ID or a workspace status value.","tags":["Conversations"],"security":[{"bearerAuth":[]}],"x-required-scope":"conversations:read","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"customer_id","in":"query","schema":{"type":"string"},"description":"Filter by a customer public ULID."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Exact status value, including workspace custom statuses."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversationListResponse"}}}}}}},"\/conversations\/{conversation}":{"get":{"operationId":"getConversation","summary":"Get a conversation","description":"Read a conversation summary. Internal metadata, credentials and staff notes are not returned.","tags":["Conversations"],"security":[{"bearerAuth":[]}],"x-required-scope":"conversations:read","parameters":[{"name":"conversation","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26},"description":"Public ULID of a resource in the key\u2019s workspace."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversationResponse"}}}}}}},"\/conversations\/{conversation}\/messages":{"get":{"operationId":"listMessages","summary":"List public messages","description":"Read public messages in creation order, oldest first. Internal notes, system events and deleted messages are excluded. attachment_count describes attachments; this endpoint does not return file download URLs.","tags":["Conversations"],"security":[{"bearerAuth":[]}],"x-required-scope":"conversations:read","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"conversation","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26},"description":"Public ULID of a resource in the key\u2019s workspace."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MessageListResponse"}}}}}}},"\/widget\/identity-tokens":{"post":{"operationId":"issueIdentityToken","summary":"Issue a widget identity token","description":"Issue a signed token for the widget selected for this API key. Configure the widget signing secret first. subject is bound permanently to the selected customer; attempting to reuse it for a different customer returns 409. Derive both subject and customer_id on your trusted backend from its authenticated user.","tags":["Widget identity"],"security":[{"bearerAuth":[]}],"x-required-scope":"widget:identify","parameters":[],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/IdentityTokenResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/IdentityRequest"}}}}}},"\/tickets":{"get":{"summary":"List tickets","operationId":"getTickets","description":"Workspace tickets, optionally filtered by customer or status.","x-required-scope":"tickets:read","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"customer_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketListResponse"}}}}}},"post":{"summary":"Create a ticket","operationId":"postTickets","description":"Create an open API ticket through the normal workspace workflow, billing limits and notifications.","x-required-scope":"tickets:write","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Stable key for this operation. Replays a matching successful request."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateTicket"}}}}}},"\/customers\/{customer}\/tickets":{"get":{"summary":"List customer tickets","operationId":"getCustomersCustomerTickets","description":"","x-required-scope":"tickets:read","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"customer","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketListResponse"}}}}}}},"\/tickets\/{ticket}":{"get":{"summary":"Get a ticket","operationId":"getTicketsTicket","description":"Public-facing fields only. Internal notes and service target snapshots are excluded.","x-required-scope":"tickets:read","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"ticket","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketResponse"}}}}}}},"\/tickets\/{ticket}\/replies":{"get":{"summary":"List public ticket replies","operationId":"getTicketsTicketReplies","description":"Public replies only. Attachment counts are returned without file download URLs.","x-required-scope":"tickets:read","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"ticket","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketReplyListResponse"}}}}}},"post":{"summary":"Submit a customer reply","operationId":"postTicketsTicketReplies","description":"The customer must own the ticket. Closed tickets reject replies with 422. Text-only JSON request.","x-required-scope":"tickets:write","security":[{"bearerAuth":[]}],"tags":["Tickets"],"parameters":[{"name":"ticket","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Stable key for this operation. Replays a matching successful request."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TicketReplyResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateTicketReply"}}}}}},"\/feature-request-boards":{"get":{"summary":"List feature request boards","operationId":"getFeatureRequestBoards","description":"","x-required-scope":"feature_requests:read","security":[{"bearerAuth":[]}],"tags":["Feature requests"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FeatureRequestBoardListResponse"}}}}}}},"\/feature-requests":{"get":{"summary":"List feature requests","operationId":"getFeatureRequests","description":"visibility=public returns visible requests on public boards. Other reads are workspace-scoped and must be authorized by the integrating backend.","x-required-scope":"feature_requests:read","security":[{"bearerAuth":[]}],"tags":["Feature requests"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"customer_id","in":"query","schema":{"type":"string"}},{"name":"board_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"visibility","in":"query","schema":{"type":"string"}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FeatureRequestListResponse"}}}}}},"post":{"summary":"Create a feature request","operationId":"postFeatureRequests","description":"New, private, source api. The workspace team reviews and publishes requests through the normal workflow.","x-required-scope":"feature_requests:write","security":[{"bearerAuth":[]}],"tags":["Feature requests"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Stable key for this operation. Replays a matching successful request."}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"201":{"description":"Created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FeatureRequestResponse"}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateFeatureRequest"}}}}}},"\/customers\/{customer}\/feature-requests":{"get":{"summary":"List customer feature requests","operationId":"getCustomersCustomerFeatureRequests","description":"","x-required-scope":"feature_requests:read","security":[{"bearerAuth":[]}],"tags":["Feature requests"],"parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum records per page."},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":2048},"description":"Use meta.pagination.next_cursor unchanged."},{"name":"board_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"visibility","in":"query","schema":{"type":"string"}},{"name":"customer","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FeatureRequestListResponse"}}}}}}},"\/feature-requests\/{featureRequest}":{"get":{"summary":"Get a feature request","operationId":"getFeatureRequestsFeaturerequest","description":"","x-required-scope":"feature_requests:read","security":[{"bearerAuth":[]}],"tags":["Feature requests"],"parameters":[{"name":"featureRequest","in":"path","required":true,"schema":{"type":"string","minLength":26,"maxLength":26}}],"responses":{"400":{"description":"Invalid JSON or missing Idempotency-Key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Invalid, expired or revoked API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Insufficient scope or workspace permission","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Resource not found in this workspace","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not supported","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Idempotency or identity conflict","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"413":{"description":"Body exceeds 64 KB","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"415":{"description":"Use application\/json","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Rate limit reached","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"500":{"description":"Unexpected server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"200":{"description":"Success","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/FeatureRequestResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tcr_<public-key-id>.<secret>","description":"Create a scoped key in Settings \/ API access. Never use the public widget key or identity signing secret as a Bearer credential."}},"schemas":{"Customer":{"type":"object","properties":{"id":{"type":"string","description":"Public ULID. "},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"company":{"type":["string","null"]},"external_id":{"type":["string","null"]},"attributes":{"type":"object","additionalProperties":true,"description":"Canonical customer attributes. Website-supplied attributes are returned separately in widget_context."},"tags":{"type":"array","items":{"type":"string"}},"is_anonymous":{"type":"boolean"},"source":{"type":"string"},"first_seen_at":{"type":["string","null"],"format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"widget_context":{"type":"array","description":"Present in show, lookup and write responses only. Up to five recent website attribute snapshots. Website attributes are unverified context.","items":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":true},"source":{"const":"website"},"updated_at":{"type":["string","null"]}}}}},"required":["id","name","email","phone","company","external_id","attributes","tags","is_anonymous","source","first_seen_at","last_seen_at","created_at","updated_at"]},"CustomerWrite":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":160},"email":{"type":["string","null"],"maxLength":255,"format":"email"},"phone":{"type":["string","null"],"maxLength":40},"company":{"type":["string","null"],"maxLength":160},"external_id":{"type":["string","null"],"maxLength":160},"attributes":{"type":"object","maxProperties":50,"propertyNames":{"pattern":"^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$"},"additionalProperties":{"type":["string","number","boolean","null"],"maxLength":1000},"description":"Flat attributes; merges by key. Null removes a key. Total stored attributes: 50 keys \/ 20 KB. prototype, constructor and __proto__ are reserved."}},"additionalProperties":false,"minProperties":1},"CustomerUpsert":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":160},"email":{"type":["string","null"],"maxLength":255,"format":"email"},"phone":{"type":["string","null"],"maxLength":40},"company":{"type":["string","null"],"maxLength":160},"external_id":{"type":"string","minLength":1,"maxLength":160},"attributes":{"type":"object","maxProperties":50,"propertyNames":{"pattern":"^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$"},"additionalProperties":{"type":["string","number","boolean","null"],"maxLength":1000},"description":"Flat attributes; merges by key. Null removes a key. Total stored attributes: 50 keys \/ 20 KB. prototype, constructor and __proto__ are reserved."}},"additionalProperties":false,"minProperties":1,"required":["external_id"]},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"customer_id":{"type":["string","null"]},"subject":{"type":["string","null"]},"status":{"type":"string"},"priority":{"type":"string"},"channel":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","customer_id","subject","status","priority","channel","origin","created_at","updated_at"]},"Message":{"type":"object","properties":{"id":{"type":"string"},"body":{"type":["string","null"]},"sender":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":["string","null"]}}},"attachment_count":{"type":"integer","minimum":0},"sent_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"read_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"}},"required":["id","body","sender","attachment_count","sent_at","delivered_at","read_at","created_at"]},"IdentityRequest":{"type":"object","properties":{"customer_id":{"type":"string","minLength":26,"maxLength":26},"subject":{"type":"string","minLength":1,"maxLength":160,"description":"Stable authenticated application user ID, chosen on your server. Case-sensitive and permanently bound to this customer for this widget."},"ttl_seconds":{"type":"integer","minimum":60,"maximum":3600,"default":900}},"required":["customer_id","subject"]},"IdentityToken":{"type":"object","properties":{"identity_token":{"type":"string","description":"Short-lived tcid1 proof, safe to pass to the authenticated customer\u2019s browser."},"expires_at":{"type":"string","format":"date-time"}},"required":["identity_token","expires_at"]},"ApiContext":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"widget_id":{"type":["string","null"],"description":"Selected widget for identity tokens, when configured."},"scopes":{"type":"array","items":{"type":"string"}},"expires_at":{"type":["string","null"],"format":"date-time","description":"Null means the key never expires."}}},"Pagination":{"type":"object","properties":{"per_page":{"type":"integer"},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["per_page","next_cursor","has_more"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":["object","array"],"additionalProperties":true}},"required":["code","message","details"]}},"required":["error"]},"CustomerResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Customer"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"CustomerListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Customer"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"ConversationResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Conversation"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"ConversationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Conversation"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"MessageResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Message"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"MessageListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Message"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"IdentityTokenResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/IdentityToken"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"ApiContextResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/ApiContext"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"Ticket":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"customer_id":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string"},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"source":{"type":"string"},"department":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","reference","customer_id","title","description","status","priority","source","department","created_at","updated_at"]},"TicketResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Ticket"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"TicketListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Ticket"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"TicketReply":{"type":"object","properties":{"id":{"type":"string"},"body":{"type":["string","null"]},"sender":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":["string","null"]}}},"attachment_count":{"type":"integer"},"sent_at":{"type":"string","format":"date-time"}},"required":["id","body","sender","attachment_count","sent_at"]},"TicketReplyResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/TicketReply"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"TicketReplyListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/TicketReply"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"FeatureRequest":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"customer_id":{"type":["string","null"]},"board":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string"},"visibility":{"type":"string","enum":["public","private"]},"vote_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","reference","customer_id","board","title","description","status","visibility","vote_count","created_at","updated_at"]},"FeatureRequestResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/FeatureRequest"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"FeatureRequestListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/FeatureRequest"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"FeatureRequestBoard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"is_public":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"is_default":{"type":"boolean"}},"required":["id","name","description","is_public","accepts_submissions","is_default"]},"FeatureRequestBoardResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/FeatureRequestBoard"},"meta":{"type":["object","array"]}},"required":["data","meta"]},"FeatureRequestBoardListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/FeatureRequestBoard"}},"meta":{"type":"object","properties":{"pagination":{"$ref":"#\/components\/schemas\/Pagination"}}}},"required":["data","meta"]},"CreateTicket":{"type":"object","additionalProperties":false,"required":["customer_id","title"],"properties":{"customer_id":{"type":"string","minLength":26,"maxLength":26},"title":{"type":"string","maxLength":180,"minLength":1},"description":{"type":["string","null"],"maxLength":10000},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal"},"department_id":{"type":["string","null"],"minLength":26,"maxLength":26}}},"CreateTicketReply":{"type":"object","additionalProperties":false,"required":["customer_id","body"],"properties":{"customer_id":{"type":"string","minLength":26,"maxLength":26},"body":{"type":"string","minLength":1,"maxLength":10000}}},"CreateFeatureRequest":{"type":"object","additionalProperties":false,"required":["customer_id","title","description"],"properties":{"customer_id":{"type":"string","minLength":26,"maxLength":26},"board_id":{"type":["string","null"],"minLength":26,"maxLength":26},"title":{"type":"string","minLength":1,"maxLength":180},"description":{"type":"string","minLength":1,"maxLength":10000}}}}}}