{ "openapi": "3.1.0", "info": { "title": "KLCT API", "version": "1.0.0", "summary": "Contacts, tickets, chat, changelog, feedback, calls and webhooks for a KLCT account.", "description": "Account-scoped REST API for KLCT. Authenticate with an account API key or an OAuth 2.1 access token.\n\nGuides, examples and the MCP connector: https://app.klctai.com/developers", "contact": { "name": "KLCT developer support", "url": "https://app.klctai.com/developers" } }, "servers": [ { "url": "https://app.klctai.com/api", "description": "KLCT" } ], "tags": [ { "name": "Account", "description": "Identify the account a token belongs to and keep its brand in step with your product." }, { "name": "Contacts", "description": "The people your account talks to. Contacts are shared by calls, chat, tickets, campaigns and sequences." }, { "name": "Contact lists", "description": "Groups of contacts used as audiences for campaigns and AI call batches. These routes need a valid token but no specific scope." }, { "name": "Calls", "description": "Calls the AI agents and your team made or received." }, { "name": "Tickets", "description": "Helpdesk tickets from email, chat, forms and the API. Replies go to the customer by email, or into the chat when the ticket came from chat. Tickets are never deleted through the API. Needs the Support module on the account." }, { "name": "Chat conversations", "description": "Live chat and messaging threads (web chat, WhatsApp, Instagram, email). Needs the Support module on the account." }, { "name": "Changelog", "description": "The release notes on your customer portal. Use this to publish from a release pipeline. Publishing through the API never emails subscribers; entries are never deleted. Needs the Changelog module on the account." }, { "name": "Feedback and roadmap", "description": "The feature requests and roadmap from your customer portal. Read-only. Author names and emails are never returned. Needs the Feedback board and Roadmap modules on the account." }, { "name": "Events and webhooks", "description": "Send events into KLCT to start sequences, and subscribe to events KLCT sends back. See the Webhooks guide for payloads and the signature check." }, { "name": "Meetings", "description": "Bookable meeting types, for embedding a booking link in another product." } ], "paths": { "/platform/account": { "get": { "operationId": "getAccount", "summary": "Get the connected account", "description": "Returns which KLCT account the token belongs to and whether billing is active. Call this first after connecting to confirm you hold the right account.\n\nRequires scope `identity`.", "tags": [ "Account" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "The KLCT account id." }, "name": { "type": "string", "description": "Account name." }, "billing_active": { "type": "boolean", "description": "False when the account has no active plan yet." }, "setup_url": { "type": "string", "description": "Where a person can finish setup when billing is not active, otherwise null." } } }, "example": { "account_id": 4821, "name": "Acme Dental", "billing_active": true, "setup_url": null } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"identity\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "identity" ] } ], "x-klct-scope": "identity" } }, "/platform/branding": { "put": { "operationId": "updateBranding", "summary": "Set the account brand", "description": "Updates the logo, colors, website and typeface KLCT uses in emails, pages and social images. Send only the fields you want to change. Never reads or deletes anything else.\n\nRequires scope `branding:write`.", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_color": { "type": "string", "description": "Hex color, for example #1D4ED8.", "example": "#1D4ED8" }, "secondary_color": { "type": "string", "description": "Hex color." }, "accent_color": { "type": "string", "description": "Hex color." }, "button_color": { "type": "string", "description": "Hex color for buttons." }, "button_text_color": { "type": "string", "description": "Hex color for button text." }, "logo_url": { "type": "string", "description": "HTTPS URL of the logo.", "example": "https://acme.example/logo.png" }, "email_logo_url": { "type": "string", "description": "HTTPS URL of the logo used in email headers." }, "square_logo_url": { "type": "string", "description": "HTTPS URL of a square logo." }, "favicon_url": { "type": "string", "description": "HTTPS URL of the favicon." }, "website_url": { "type": "string", "description": "HTTPS URL of the main website." }, "from_name": { "type": "string", "description": "Sender name on emails, up to 120 characters." }, "brand_voice": { "type": "string", "description": "How the brand should sound, up to 2000 characters. Used by the AI writers." }, "font_family": { "type": "string", "description": "One of the typefaces KLCT offers." }, "socials": { "type": "object", "description": "Social profile URLs keyed by network (HTTPS only).", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when saved." }, "updated": { "type": "array", "description": "The fields that were changed.", "items": { "type": "string", "description": "Field name" } } } }, "example": { "ok": true, "updated": [ "primary_color", "logo_url" ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"branding:write\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "branding:write" ] } ], "x-klct-scope": "branding:write" } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Newest first. Page through with `page` and `per_page`.\n\nRequires scope `contacts:read`.", "tags": [ "Contacts" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "description": "The page of contacts.", "items": { "type": "object", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email address." }, "phone": { "type": "string", "description": "Phone number in E.164 form (+15551234567)." }, "company": { "type": "string", "description": "Company name." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "tags": { "type": "array", "description": "Free-form tags.", "items": { "type": "string", "description": "Tag" } }, "metadata": { "type": "object", "description": "Your own key/value data. Merged on update, never replaced.", "additionalProperties": true }, "lead_status": { "type": "string", "description": "Pipeline stage KLCT assigned." }, "created_at": { "type": "string", "description": "When the contact was created.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "contacts": [ { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567", "company": "Acme Dental", "website": null, "country": "US", "tags": [ "vip" ], "metadata": { "crm_id": "c_77" }, "lead_status": "new", "created_at": "2026-10-01T14:03:22Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"contacts:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:read" ] } ], "x-klct-scope": "contacts:read" } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Get a contact", "description": "Requires scope `contacts:read`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email address." }, "phone": { "type": "string", "description": "Phone number in E.164 form (+15551234567)." }, "company": { "type": "string", "description": "Company name." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "tags": { "type": "array", "description": "Free-form tags.", "items": { "type": "string", "description": "Tag" } }, "metadata": { "type": "object", "description": "Your own key/value data. Merged on update, never replaced.", "additionalProperties": true }, "lead_status": { "type": "string", "description": "Pipeline stage KLCT assigned." }, "created_at": { "type": "string", "description": "When the contact was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } } }, "example": { "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567", "company": "Acme Dental", "website": null, "country": "US", "tags": [ "vip" ], "metadata": { "crm_id": "c_77" }, "lead_status": "new", "created_at": "2026-10-01T14:03:22Z", "updated_at": "2026-10-02T09:00:00Z" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"contacts:read\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:read" ] } ], "x-klct-scope": "contacts:read" }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Send only the fields to change. `metadata` is merged key by key, so you can add one key without resending the rest. Contacts are never deleted through the API.\n\nRequires scope `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Contact id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "First name. Cannot be blank.", "example": "Dana" }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email address." }, "phone": { "type": "string", "description": "Phone in any common format; stored as E.164. An unparseable value is rejected.", "example": "+15551234567" }, "company": { "type": "string", "description": "Company." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "metadata": { "type": "object", "description": "Merged into the existing metadata.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email address." }, "phone": { "type": "string", "description": "Phone number in E.164 form (+15551234567)." }, "company": { "type": "string", "description": "Company name." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "tags": { "type": "array", "description": "Free-form tags.", "items": { "type": "string", "description": "Tag" } }, "metadata": { "type": "object", "description": "Your own key/value data. Merged on update, never replaced.", "additionalProperties": true }, "lead_status": { "type": "string", "description": "Pipeline stage KLCT assigned." }, "created_at": { "type": "string", "description": "When the contact was created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } } }, "example": { "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567", "company": "Acme Dental", "website": null, "country": "US", "tags": [ "vip" ], "metadata": { "crm_id": "c_77" }, "lead_status": "new", "created_at": "2026-10-01T14:03:22Z", "updated_at": "2026-10-02T09:00:00Z" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"contacts:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:write" ] } ], "x-klct-scope": "contacts:write" } }, "/contacts/create": { "post": { "operationId": "createContacts", "summary": "Create one or many contacts", "description": "Send one contact's fields at the top level, or a `contacts` array to create several in one transaction (any invalid row rejects the whole batch). Phone must be `+1` plus ten digits. Creating the same email twice creates two contacts; use `POST /platform/contacts/sync` when you want create-or-update by email.\n\nRequires scope `contacts:write`.", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "First name.", "example": "Dana" }, "last_name": { "type": "string", "description": "Last name.", "example": "Cole" }, "email": { "type": "string", "description": "Email address.", "example": "dana@acme.example" }, "phone": { "type": "string", "description": "+1 followed by ten digits.", "example": "+15551234567" }, "company": { "type": "string", "description": "Company." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "metadata": { "type": "object", "description": "Your own key/value data.", "additionalProperties": true }, "contacts": { "type": "array", "description": "Alternative to the top-level fields: several contacts at once.", "items": { "type": "object", "description": "A contact with the same fields as above.", "additionalProperties": true } } }, "required": [ "name", "last_name", "email", "phone" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "object", "description": "One object for a single contact, an array of them for a batch.", "properties": { "contact_id": { "type": "integer", "description": "New contact id." }, "name": { "type": "string", "description": "First name." } } } } }, "example": { "contacts": { "contact_id": 90412, "name": "Dana" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"contacts:write\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:write" ] } ], "x-klct-scope": "contacts:write" } }, "/platform/contacts/sync": { "post": { "operationId": "syncContacts", "summary": "Create or update contacts by email", "description": "Up to 200 contacts per call. A contact whose email already exists is updated: blank fields are filled, existing values are kept, tags are unioned and metadata is merged. Rows that fail validation are reported in `errors` without stopping the rest. Limited to 30 calls per minute.\n\nRequires scope `contacts:write`.", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "description": "Between 1 and 200 contacts.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email, the match key.", "example": "dana@acme.example" }, "name": { "type": "string", "description": "First name.", "example": "Dana" }, "last_name": { "type": "string", "description": "Last name." }, "phone": { "type": "string", "description": "Any common phone format; ignored if it cannot be parsed." }, "company": { "type": "string", "description": "Company." }, "tags": { "type": "array", "description": "Up to 10 tags, 50 characters each.", "items": { "type": "string", "description": "Tag" } }, "metadata": { "type": "object", "description": "Key/value data, merged.", "additionalProperties": true } }, "required": [ "email" ] } } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer", "description": "Contacts created." }, "updated": { "type": "integer", "description": "Contacts updated." }, "errors": { "type": "array", "description": "Rows that were skipped.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position in the request." }, "error": { "type": "string", "description": "Why the row was skipped." } } } } } }, "example": { "created": 1, "updated": 0, "errors": [] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"contacts:write\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "contacts:write" ] } ], "x-klct-scope": "contacts:write" } }, "/contactslists/list": { "get": { "operationId": "listContactLists", "summary": "List contact lists", "description": "", "tags": [ "Contact lists" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "All lists in the account.", "items": { "type": "object", "description": "A contact list.", "additionalProperties": true } } } }, "example": { "data": [ { "contacts_list_id": 12, "name": "Spring leads", "target_industry": "Dental" } ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/create": { "post": { "operationId": "createContactList", "summary": "Create a contact list", "description": "", "tags": [ "Contact lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name.", "example": "Spring leads" }, "target_industry": { "type": "string", "description": "Industry the list targets.", "example": "Dental" }, "notes": { "type": "string", "description": "Notes about the list.", "example": "Imported from the open house" }, "metadata": { "type": "object", "description": "Your own key/value data.", "additionalProperties": true } }, "required": [ "name", "target_industry", "notes" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_list_id": { "type": "integer", "description": "New list id." } } }, "example": { "contact_list_id": 12 } } } }, "401": { "description": "Missing, invalid or expired token.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/update": { "post": { "operationId": "updateContactList", "summary": "Rename or edit a contact list", "description": "", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name.", "example": "Spring leads 2026" }, "target_industry": { "type": "string", "description": "Industry." }, "metadata": { "type": "object", "description": "Merged into existing metadata.", "additionalProperties": true } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_list_id": { "type": "integer", "description": "List id." } } }, "example": { "contact_list_id": 12 } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/delete": { "post": { "operationId": "deleteContactList", "summary": "Delete a contact list", "description": "Deletes the list, not the contacts in it.", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string", "description": "Confirmation sentence." } } }, "example": { "success": "Contact list deleted with success!" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/get_contacts": { "get": { "operationId": "listContactListMembers", "summary": "List the contacts in a list", "description": "", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Members of the list.", "items": { "type": "object", "description": "A contact.", "additionalProperties": true } } } }, "example": { "data": [ { "contact_id": 90412, "name": "Dana" } ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/create_sync_contacts": { "post": { "operationId": "createAndSyncListContacts", "summary": "Create contacts and put them in a list", "description": "Creates each contact (or updates the existing one with the same phone or email) and adds it to the list.", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "description": "Contacts to create and add.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "First name.", "example": "Dana" }, "email": { "type": "string", "description": "Email.", "example": "dana@acme.example" }, "last_name": { "type": "string", "description": "Last name." }, "phone": { "type": "string", "description": "Phone.", "example": "+15551234567" }, "company": { "type": "string", "description": "Company." }, "website": { "type": "string", "description": "Website." }, "country": { "type": "string", "description": "Country." }, "metadata": { "type": "object", "description": "Key/value data.", "additionalProperties": true } }, "required": [ "name", "email" ] } } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string", "description": "Confirmation sentence." } } }, "example": { "success": "The contacts where synced with success!" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/sync_contacts": { "post": { "operationId": "syncListContacts", "summary": "Set the members of a list", "description": "Sets the list membership from `contacts_ids`.", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name (this endpoint requires it).", "example": "Spring leads" }, "contacts_ids": { "type": "array", "description": "Contact ids that should be in the list.", "example": [ 90412 ], "items": { "type": "integer", "description": "Contact id" } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string", "description": "Confirmation sentence." } } }, "example": { "success": "The contacts where synced with success!" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/contactslists/{contactList}/remove_contacts": { "post": { "operationId": "removeListContacts", "summary": "Remove contacts from a list", "description": "Removes membership only. The contacts themselves are kept.", "tags": [ "Contact lists" ], "parameters": [ { "name": "contactList", "in": "path", "required": true, "description": "Contact list id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts_ids": { "type": "array", "description": "Contact ids to remove.", "example": [ 90412 ], "items": { "type": "integer", "description": "Contact id" } } }, "required": [ "contacts_ids" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "string", "description": "Confirmation sentence." } } }, "example": { "success": "Contacts removed" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/calls": { "get": { "operationId": "listCalls", "summary": "List calls", "description": "Newest first, with outcome and duration.\n\nRequires scope `calls:read`.", "tags": [ "Calls" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "description": "The page of calls.", "items": { "type": "object", "properties": { "phone_call_id": { "type": "integer", "description": "Call id." }, "contact_id": { "type": "integer", "description": "The contact on the call." }, "from": { "type": "string", "description": "Caller number." }, "to": { "type": "string", "description": "Dialed number." }, "status": { "type": "string", "description": "Call status." }, "duration": { "type": "integer", "description": "Seconds." }, "interest_level": { "type": "string", "description": "How interested the AI graded the contact." }, "start_time": { "type": "string", "description": "When the call started.", "format": "date-time" }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "calls": [ { "phone_call_id": 55120, "contact_id": 90412, "from": "+15559876543", "to": "+15551234567", "status": "completed", "duration": 142, "interest_level": "high", "start_time": "2026-10-02T15:10:00Z", "created_at": "2026-10-02T15:09:41Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"calls:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "calls:read" ] } ], "x-klct-scope": "calls:read" } }, "/tickets": { "get": { "operationId": "listTickets", "summary": "List tickets", "description": "Newest first. Filter by status, contact, search text, or what changed since a time (handy for incremental sync).\n\nRequires scope `tickets:read`.", "tags": [ "Tickets" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "One exact status, or `unresolved` for every status that still needs work.", "schema": { "type": "string", "description": "One exact status, or `unresolved` for every status that still needs work.", "example": "unresolved" } }, { "name": "q", "in": "query", "required": false, "description": "Matches the subject or ticket number.", "schema": { "type": "string", "description": "Matches the subject or ticket number." } }, { "name": "contact_id", "in": "query", "required": false, "description": "Only tickets for this contact.", "schema": { "type": "integer", "description": "Only tickets for this contact." } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only tickets changed at or after this time.", "schema": { "type": "string", "description": "Only tickets changed at or after this time.", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "description": "The page of tickets.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ticket id." }, "ticket_number": { "type": "string", "description": "Human reference such as SUP-1042." }, "subject": { "type": "string", "description": "Subject line." }, "status": { "type": "string", "description": "Current status." }, "priority": { "type": "integer", "description": "0 (lowest) to 4 (highest)." }, "source": { "type": "string", "description": "How it arrived: email, chat, form, api and others." }, "contact": { "type": "object", "description": "The requester, or null.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "due_at": { "type": "string", "description": "Due date, or null.", "format": "date-time" }, "first_response_at": { "type": "string", "description": "When a person first replied, or null.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "tickets": [ { "id": 1042, "ticket_number": "SUP-1042", "subject": "Cannot log in on mobile", "status": "open", "priority": 2, "source": "email", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567" }, "due_at": null, "first_response_at": null, "resolved_at": null, "created_at": "2026-10-14T09:12:00Z", "updated_at": "2026-10-14T09:12:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"tickets:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:read" ] } ], "x-klct-scope": "tickets:read" }, "post": { "operationId": "createTicket", "summary": "Create a ticket", "description": "Creates an open ticket with source `api`. This records the ticket and fires the `ticket.created` webhook; it does not send an acknowledgement email to the requester.\n\nRequires scope `tickets:write`.", "tags": [ "Tickets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject line, up to 255 characters.", "example": "Cannot log in on mobile" }, "description": { "type": "string", "description": "What happened, up to 20000 characters.", "example": "The app says my password is wrong." }, "priority": { "type": "integer", "description": "0 to 4. Defaults to 0.", "maximum": 4, "minimum": 0, "example": 2 }, "contact_id": { "type": "integer", "description": "Requester. Must be a contact in this account.", "example": 90412 }, "due_at": { "type": "string", "description": "When it should be handled by.", "format": "date-time" } }, "required": [ "subject" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ticket id." }, "ticket_number": { "type": "string", "description": "Human reference such as SUP-1042." }, "subject": { "type": "string", "description": "Subject line." }, "status": { "type": "string", "description": "Current status." }, "priority": { "type": "integer", "description": "0 (lowest) to 4 (highest)." }, "source": { "type": "string", "description": "How it arrived: email, chat, form, api and others." }, "contact": { "type": "object", "description": "The requester, or null.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "due_at": { "type": "string", "description": "Due date, or null.", "format": "date-time" }, "first_response_at": { "type": "string", "description": "When a person first replied, or null.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "description": { "type": "string", "description": "The original request text." }, "reply_channel": { "type": "string", "description": "How a reply reaches the customer.", "enum": [ "chat", "email" ] }, "conversation_id": { "type": "integer", "description": "The chat conversation behind the ticket, or null." }, "messages": { "type": "array", "description": "The customer-visible thread. Internal notes are never included.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "direction": { "type": "string", "description": "in is from the customer, out is from your team.", "enum": [ "in", "out" ] }, "sender_type": { "type": "string", "description": "Who wrote it." }, "sender_name": { "type": "string", "description": "Display name only." }, "body": { "type": "string", "description": "Message text." }, "attachments": { "type": "array", "description": "Attachment details. Files themselves are not downloadable through the API.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name." }, "mime": { "type": "string", "description": "Content type." }, "size": { "type": "integer", "description": "Bytes." } } } }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } } } } } } }, "example": { "ticket": { "id": 1042, "ticket_number": "SUP-1042", "subject": "Cannot log in on mobile", "status": "open", "priority": 2, "source": "email", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567" }, "due_at": null, "first_response_at": null, "resolved_at": null, "created_at": "2026-10-14T09:12:00Z", "updated_at": "2026-10-14T09:12:00Z", "description": "The app says my password is wrong but the website accepts it.", "reply_channel": "email", "conversation_id": null, "messages": [ { "id": 3301, "direction": "in", "sender_type": "contact", "sender_name": "Dana Cole", "body": "The app says my password is wrong but the website accepts it.", "attachments": [], "created_at": "2026-10-14T09:12:00Z" } ] } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"tickets:write\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:write" ] } ], "x-klct-scope": "tickets:write" } }, "/tickets/{id}": { "get": { "operationId": "getTicket", "summary": "Get a ticket with its conversation", "description": "Includes the customer-visible message thread. Internal notes and staff details beyond a display name are left out.\n\nRequires scope `tickets:read`.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ticket id." }, "ticket_number": { "type": "string", "description": "Human reference such as SUP-1042." }, "subject": { "type": "string", "description": "Subject line." }, "status": { "type": "string", "description": "Current status." }, "priority": { "type": "integer", "description": "0 (lowest) to 4 (highest)." }, "source": { "type": "string", "description": "How it arrived: email, chat, form, api and others." }, "contact": { "type": "object", "description": "The requester, or null.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "due_at": { "type": "string", "description": "Due date, or null.", "format": "date-time" }, "first_response_at": { "type": "string", "description": "When a person first replied, or null.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "description": { "type": "string", "description": "The original request text." }, "reply_channel": { "type": "string", "description": "How a reply reaches the customer.", "enum": [ "chat", "email" ] }, "conversation_id": { "type": "integer", "description": "The chat conversation behind the ticket, or null." }, "messages": { "type": "array", "description": "The customer-visible thread. Internal notes are never included.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "direction": { "type": "string", "description": "in is from the customer, out is from your team.", "enum": [ "in", "out" ] }, "sender_type": { "type": "string", "description": "Who wrote it." }, "sender_name": { "type": "string", "description": "Display name only." }, "body": { "type": "string", "description": "Message text." }, "attachments": { "type": "array", "description": "Attachment details. Files themselves are not downloadable through the API.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name." }, "mime": { "type": "string", "description": "Content type." }, "size": { "type": "integer", "description": "Bytes." } } } }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } } } } } } }, "example": { "ticket": { "id": 1042, "ticket_number": "SUP-1042", "subject": "Cannot log in on mobile", "status": "open", "priority": 2, "source": "email", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567" }, "due_at": null, "first_response_at": null, "resolved_at": null, "created_at": "2026-10-14T09:12:00Z", "updated_at": "2026-10-14T09:12:00Z", "description": "The app says my password is wrong but the website accepts it.", "reply_channel": "email", "conversation_id": null, "messages": [ { "id": 3301, "direction": "in", "sender_type": "contact", "sender_name": "Dana Cole", "body": "The app says my password is wrong but the website accepts it.", "attachments": [], "created_at": "2026-10-14T09:12:00Z" } ] } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"tickets:read\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:read" ] } ], "x-klct-scope": "tickets:read" }, "patch": { "operationId": "updateTicket", "summary": "Update a ticket", "description": "Send only the fields to change. Moving to `resolved` or `closed` stamps `resolved_at`; moving a resolved ticket back to an open status counts as a reopen. Each change is written to the ticket history.\n\nRequires scope `tickets:write`.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "New subject." }, "description": { "type": "string", "description": "New description." }, "priority": { "type": "integer", "description": "0 to 4.", "maximum": 4, "minimum": 0 }, "status": { "type": "string", "description": "A valid ticket status, for example open, pending, resolved, closed.", "example": "resolved" }, "due_at": { "type": "string", "description": "New due date.", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "id": { "type": "integer", "description": "Ticket id." }, "ticket_number": { "type": "string", "description": "Human reference such as SUP-1042." }, "subject": { "type": "string", "description": "Subject line." }, "status": { "type": "string", "description": "Current status." }, "priority": { "type": "integer", "description": "0 (lowest) to 4 (highest)." }, "source": { "type": "string", "description": "How it arrived: email, chat, form, api and others." }, "contact": { "type": "object", "description": "The requester, or null.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "due_at": { "type": "string", "description": "Due date, or null.", "format": "date-time" }, "first_response_at": { "type": "string", "description": "When a person first replied, or null.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "description": { "type": "string", "description": "The original request text." }, "reply_channel": { "type": "string", "description": "How a reply reaches the customer.", "enum": [ "chat", "email" ] }, "conversation_id": { "type": "integer", "description": "The chat conversation behind the ticket, or null." }, "messages": { "type": "array", "description": "The customer-visible thread. Internal notes are never included.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "direction": { "type": "string", "description": "in is from the customer, out is from your team.", "enum": [ "in", "out" ] }, "sender_type": { "type": "string", "description": "Who wrote it." }, "sender_name": { "type": "string", "description": "Display name only." }, "body": { "type": "string", "description": "Message text." }, "attachments": { "type": "array", "description": "Attachment details. Files themselves are not downloadable through the API.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name." }, "mime": { "type": "string", "description": "Content type." }, "size": { "type": "integer", "description": "Bytes." } } } }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } } } } } } }, "example": { "ticket": { "status": "resolved", "id": 1042, "ticket_number": "SUP-1042", "subject": "Cannot log in on mobile", "priority": 2, "source": "email", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": "+15551234567" }, "due_at": null, "first_response_at": null, "resolved_at": null, "created_at": "2026-10-14T09:12:00Z", "updated_at": "2026-10-14T09:12:00Z", "description": "The app says my password is wrong but the website accepts it.", "reply_channel": "email", "conversation_id": null, "messages": [ { "id": 3301, "direction": "in", "sender_type": "contact", "sender_name": "Dana Cole", "body": "The app says my password is wrong but the website accepts it.", "attachments": [], "created_at": "2026-10-14T09:12:00Z" } ] } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"tickets:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:write" ] } ], "x-klct-scope": "tickets:write" } }, "/tickets/{id}/notes": { "post": { "operationId": "addTicketNote", "summary": "Add an internal note", "description": "A note for your team. It is recorded in the ticket history and is never shown to or sent to the customer.\n\nRequires scope `tickets:write`.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Note text, up to 10000 characters.", "example": "Reproduced on iOS 19. Passing to engineering." } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "object", "properties": { "id": { "type": "integer", "description": "Note id." }, "body": { "type": "string", "description": "Note text." }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" } } } } }, "example": { "note": { "id": 5521, "body": "Reproduced on iOS 19. Passing to engineering.", "created_at": "2026-10-14T10:02:00Z" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"tickets:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:write" ] } ], "x-klct-scope": "tickets:write" } }, "/tickets/{id}/replies": { "post": { "operationId": "replyToTicket", "summary": "Reply to the customer", "description": "Sends a real, customer-visible reply: by email, or into the chat if the ticket came from chat (which also takes the chat over from the AI). Records the first response time. Answers 422 if the requester has no email address or the send fails, and nothing is stored in that case.\n\nRequires scope `tickets:write`.", "tags": [ "Tickets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ticket id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Reply text, up to 16000 characters.", "example": "Thanks Dana, we found the cause and a fix is rolling out today." } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "channel": { "type": "string", "description": "How it was sent.", "enum": [ "chat", "email" ] }, "direction": { "type": "string", "description": "Always out." }, "body": { "type": "string", "description": "Text sent." }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } } } }, "example": { "message": { "id": 3302, "channel": "email", "direction": "out", "body": "Thanks Dana, we found the cause and a fix is rolling out today.", "created_at": "2026-10-14T10:05:00Z" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, or the Support module is switched off for the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed, or the reply could not be delivered (for example the requester has no email).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tickets:write" ] } ], "x-klct-scope": "tickets:write" } }, "/conversations": { "get": { "operationId": "listConversations", "summary": "List chat conversations", "description": "Most recently active first.\n\nRequires scope `conversations:read`.", "tags": [ "Chat conversations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "One exact status, or `unresolved` for everything not resolved or closed.", "schema": { "type": "string", "description": "One exact status, or `unresolved` for everything not resolved or closed.", "example": "unresolved" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Only conversations with this contact.", "schema": { "type": "integer", "description": "Only conversations with this contact." } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only conversations changed at or after this time.", "schema": { "type": "string", "description": "Only conversations changed at or after this time.", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "description": "The page of conversations.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Conversation id." }, "status": { "type": "string", "description": "open, pending, resolved, closed and others." }, "handling_mode": { "type": "string", "description": "Who is answering: the AI assistant or a person.", "enum": [ "ai", "human" ] }, "channel": { "type": "string", "description": "web, email, whatsapp, instagram and others." }, "subject": { "type": "string", "description": "Short title, if any." }, "priority": { "type": "string", "description": "Priority label." }, "contact": { "type": "object", "description": "The person chatting, or null if anonymous.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "ticket_id": { "type": "integer", "description": "Linked ticket, or null." }, "last_message_at": { "type": "string", "description": "Most recent customer-visible message.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "csat_rating": { "type": "integer", "description": "The customer satisfaction rating, or null." }, "created_at": { "type": "string", "description": "Started.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "conversations": [ { "id": 7781, "status": "open", "handling_mode": "ai", "channel": "web", "subject": null, "priority": "normal", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": null }, "ticket_id": null, "last_message_at": "2026-10-14T09:20:00Z", "resolved_at": null, "csat_rating": null, "created_at": "2026-10-14T09:18:00Z", "updated_at": "2026-10-14T09:20:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"conversations:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "conversations:read" ] } ], "x-klct-scope": "conversations:read" } }, "/conversations/{id}": { "get": { "operationId": "getConversation", "summary": "Get a conversation with its messages", "description": "Reading a conversation does not mark it read for your team.\n\nRequires scope `conversations:read`.", "tags": [ "Chat conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "integer", "description": "Conversation id." }, "status": { "type": "string", "description": "open, pending, resolved, closed and others." }, "handling_mode": { "type": "string", "description": "Who is answering: the AI assistant or a person.", "enum": [ "ai", "human" ] }, "channel": { "type": "string", "description": "web, email, whatsapp, instagram and others." }, "subject": { "type": "string", "description": "Short title, if any." }, "priority": { "type": "string", "description": "Priority label." }, "contact": { "type": "object", "description": "The person chatting, or null if anonymous.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "ticket_id": { "type": "integer", "description": "Linked ticket, or null." }, "last_message_at": { "type": "string", "description": "Most recent customer-visible message.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "csat_rating": { "type": "integer", "description": "The customer satisfaction rating, or null." }, "created_at": { "type": "string", "description": "Started.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "messages": { "type": "array", "description": "Customer-visible messages, oldest first. Internal notes are never included.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "sender_type": { "type": "string", "description": "Who wrote it.", "enum": [ "visitor", "operator", "ai" ] }, "sender_name": { "type": "string", "description": "Display name only." }, "body": { "type": "string", "description": "Message text." }, "attachments": { "type": "array", "description": "Attachment details only.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "File name." }, "mime": { "type": "string", "description": "Content type." }, "size": { "type": "integer", "description": "Bytes." } } } }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } } } } } } }, "example": { "conversation": { "id": 7781, "status": "open", "handling_mode": "ai", "channel": "web", "subject": null, "priority": "normal", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": null }, "ticket_id": null, "last_message_at": "2026-10-14T09:20:00Z", "resolved_at": null, "csat_rating": null, "created_at": "2026-10-14T09:18:00Z", "updated_at": "2026-10-14T09:20:00Z", "messages": [ { "id": 1, "sender_type": "visitor", "sender_name": "Dana Cole", "body": "Do you open on Sundays?", "attachments": [], "created_at": "2026-10-14T09:18:00Z" }, { "id": 2, "sender_type": "ai", "sender_name": "Assistant", "body": "Yes, 10am to 4pm.", "attachments": [], "created_at": "2026-10-14T09:18:05Z" } ] } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"conversations:read\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "conversations:read" ] } ], "x-klct-scope": "conversations:read" } }, "/conversations/{id}/messages": { "post": { "operationId": "replyToConversation", "summary": "Send a reply in a conversation", "description": "Sends a real message to the customer on the conversation's channel, and takes the conversation over from the AI (`handling_mode` becomes `human`).\n\nRequires scope `conversations:write`.", "tags": [ "Chat conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "Message text, up to 16000 characters.", "example": "Yes, we are open 10am to 4pm on Sundays." } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "integer", "description": "Message id." }, "sender_type": { "type": "string", "description": "Always operator." }, "body": { "type": "string", "description": "Text sent." }, "created_at": { "type": "string", "description": "Sent.", "format": "date-time" } } }, "handling_mode": { "type": "string", "description": "Now human." } } }, "example": { "message": { "id": 3, "sender_type": "operator", "body": "Yes, we are open 10am to 4pm on Sundays.", "created_at": "2026-10-14T09:25:00Z" }, "handling_mode": "human" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"conversations:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "conversations:write" ] } ], "x-klct-scope": "conversations:write" } }, "/conversations/{id}/resolve": { "post": { "operationId": "resolveConversation", "summary": "Resolve a conversation", "description": "Marks the conversation resolved. The customer may be asked for a rating, depending on the widget settings.\n\nRequires scope `conversations:write`.", "tags": [ "Chat conversations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "integer", "description": "Conversation id." }, "status": { "type": "string", "description": "open, pending, resolved, closed and others." }, "handling_mode": { "type": "string", "description": "Who is answering: the AI assistant or a person.", "enum": [ "ai", "human" ] }, "channel": { "type": "string", "description": "web, email, whatsapp, instagram and others." }, "subject": { "type": "string", "description": "Short title, if any." }, "priority": { "type": "string", "description": "Priority label." }, "contact": { "type": "object", "description": "The person chatting, or null if anonymous.", "properties": { "contact_id": { "type": "integer", "description": "Contact id." }, "name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email." }, "phone": { "type": "string", "description": "Phone." } } }, "ticket_id": { "type": "integer", "description": "Linked ticket, or null." }, "last_message_at": { "type": "string", "description": "Most recent customer-visible message.", "format": "date-time" }, "resolved_at": { "type": "string", "description": "When it was resolved, or null.", "format": "date-time" }, "csat_rating": { "type": "integer", "description": "The customer satisfaction rating, or null." }, "created_at": { "type": "string", "description": "Started.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } } }, "example": { "conversation": { "status": "resolved", "id": 7781, "handling_mode": "ai", "channel": "web", "subject": null, "priority": "normal", "contact": { "contact_id": 90412, "name": "Dana", "last_name": "Cole", "email": "dana@acme.example", "phone": null }, "ticket_id": null, "last_message_at": "2026-10-14T09:20:00Z", "resolved_at": null, "csat_rating": null, "created_at": "2026-10-14T09:18:00Z", "updated_at": "2026-10-14T09:20:00Z" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"conversations:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "conversations:write" ] } ], "x-klct-scope": "conversations:write" } }, "/changelog": { "get": { "operationId": "listChangelog", "summary": "List changelog entries", "description": "Requires scope `changelog:read`.", "tags": [ "Changelog" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Only drafts or only published entries.", "schema": { "type": "string", "description": "Only drafts or only published entries.", "enum": [ "draft", "published" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "description": "The page of entries.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Entry id." }, "title": { "type": "string", "description": "Title." }, "slug": { "type": "string", "description": "URL slug, unique in the portal." }, "version": { "type": "string", "description": "Version label such as v2.4.0, or null." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Category name." } } }, "labels": { "type": "array", "description": "Free-form labels such as New or Fix.", "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "draft is private, published is public once its date arrives.", "enum": [ "draft", "published" ] }, "is_live": { "type": "boolean", "description": "True when published and its date has passed, so visitors can see it." }, "published_at": { "type": "string", "description": "Publish time, or null for a draft.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "entries": [ { "id": 214, "title": "Faster ticket search", "slug": "faster-ticket-search", "version": "v2.4.0", "category": { "id": 3, "name": "Improvements" }, "labels": [ "New" ], "status": "published", "is_live": true, "published_at": "2026-10-14T12:00:00Z", "created_at": "2026-10-14T11:40:00Z", "updated_at": "2026-10-14T11:40:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"changelog:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "changelog:read" ] } ], "x-klct-scope": "changelog:read" }, "post": { "operationId": "createChangelogEntry", "summary": "Create a changelog entry", "description": "Saved as a draft unless you send `status: published`. The slug is generated from the title. Publishing fires the `changelog.published` webhook. Subscribers are not emailed.\n\nRequires scope `changelog:write`.", "tags": [ "Changelog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title, 3 to 255 characters.", "example": "Faster ticket search" }, "content": { "type": "string", "description": "Body up to 60000 characters. Plain text, Markdown or HTML; HTML is sanitized.", "example": "Searching tickets is now **twice as fast**." }, "version": { "type": "string", "description": "Version label, up to 50 characters.", "example": "v2.4.0" }, "category_id": { "type": "integer", "description": "One of this portal's categories." }, "labels": { "type": "array", "description": "Up to 10 labels, 40 characters each.", "example": [ "New" ], "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "Defaults to draft on create.", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "description": "When it goes live. Defaults to now when publishing.", "format": "date-time" } }, "required": [ "title", "content" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "integer", "description": "Entry id." }, "title": { "type": "string", "description": "Title." }, "slug": { "type": "string", "description": "URL slug, unique in the portal." }, "version": { "type": "string", "description": "Version label such as v2.4.0, or null." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Category name." } } }, "labels": { "type": "array", "description": "Free-form labels such as New or Fix.", "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "draft is private, published is public once its date arrives.", "enum": [ "draft", "published" ] }, "is_live": { "type": "boolean", "description": "True when published and its date has passed, so visitors can see it." }, "published_at": { "type": "string", "description": "Publish time, or null for a draft.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "content_html": { "type": "string", "description": "The body as sanitized HTML." } } } } }, "example": { "entry": { "id": 214, "title": "Faster ticket search", "slug": "faster-ticket-search", "version": "v2.4.0", "category": { "id": 3, "name": "Improvements" }, "labels": [ "New" ], "status": "published", "is_live": true, "published_at": "2026-10-14T12:00:00Z", "created_at": "2026-10-14T11:40:00Z", "updated_at": "2026-10-14T11:40:00Z", "content_html": "

Searching tickets is now twice as fast.

" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"changelog:write\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "changelog:write" ] } ], "x-klct-scope": "changelog:write" } }, "/changelog/{id}": { "get": { "operationId": "getChangelogEntry", "summary": "Get a changelog entry", "description": "Requires scope `changelog:read`.", "tags": [ "Changelog" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entry id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "integer", "description": "Entry id." }, "title": { "type": "string", "description": "Title." }, "slug": { "type": "string", "description": "URL slug, unique in the portal." }, "version": { "type": "string", "description": "Version label such as v2.4.0, or null." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Category name." } } }, "labels": { "type": "array", "description": "Free-form labels such as New or Fix.", "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "draft is private, published is public once its date arrives.", "enum": [ "draft", "published" ] }, "is_live": { "type": "boolean", "description": "True when published and its date has passed, so visitors can see it." }, "published_at": { "type": "string", "description": "Publish time, or null for a draft.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "content_html": { "type": "string", "description": "The body as sanitized HTML." } } } } }, "example": { "entry": { "id": 214, "title": "Faster ticket search", "slug": "faster-ticket-search", "version": "v2.4.0", "category": { "id": 3, "name": "Improvements" }, "labels": [ "New" ], "status": "published", "is_live": true, "published_at": "2026-10-14T12:00:00Z", "created_at": "2026-10-14T11:40:00Z", "updated_at": "2026-10-14T11:40:00Z", "content_html": "

Searching tickets is now twice as fast.

" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"changelog:read\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "changelog:read" ] } ], "x-klct-scope": "changelog:read" }, "patch": { "operationId": "updateChangelogEntry", "summary": "Update a changelog entry", "description": "Send only the fields to change; an empty body is rejected. Published entries can be edited. Moving a draft to `published` fires `changelog.published` once.\n\nRequires scope `changelog:write`.", "tags": [ "Changelog" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Entry id.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Title, 3 to 255 characters.", "example": "Faster ticket search" }, "content": { "type": "string", "description": "Body up to 60000 characters. Plain text, Markdown or HTML; HTML is sanitized.", "example": "Searching tickets is now **twice as fast**." }, "version": { "type": "string", "description": "Version label, up to 50 characters.", "example": "v2.4.0" }, "category_id": { "type": "integer", "description": "One of this portal's categories." }, "labels": { "type": "array", "description": "Up to 10 labels, 40 characters each.", "example": [ "New" ], "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "Defaults to draft on create.", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "description": "When it goes live. Defaults to now when publishing.", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "integer", "description": "Entry id." }, "title": { "type": "string", "description": "Title." }, "slug": { "type": "string", "description": "URL slug, unique in the portal." }, "version": { "type": "string", "description": "Version label such as v2.4.0, or null." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Category name." } } }, "labels": { "type": "array", "description": "Free-form labels such as New or Fix.", "items": { "type": "string", "description": "Label" } }, "status": { "type": "string", "description": "draft is private, published is public once its date arrives.", "enum": [ "draft", "published" ] }, "is_live": { "type": "boolean", "description": "True when published and its date has passed, so visitors can see it." }, "published_at": { "type": "string", "description": "Publish time, or null for a draft.", "format": "date-time" }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" }, "content_html": { "type": "string", "description": "The body as sanitized HTML." } } } } }, "example": { "entry": { "id": 214, "title": "Faster ticket search", "slug": "faster-ticket-search", "version": "v2.4.0", "category": { "id": 3, "name": "Improvements" }, "labels": [ "New" ], "status": "published", "is_live": true, "published_at": "2026-10-14T12:00:00Z", "created_at": "2026-10-14T11:40:00Z", "updated_at": "2026-10-14T11:40:00Z", "content_html": "

Searching tickets is now twice as fast.

" } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"changelog:write\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "changelog:write" ] } ], "x-klct-scope": "changelog:write" } }, "/feedback": { "get": { "operationId": "listFeedback", "summary": "List feedback posts", "description": "Most voted first.\n\nRequires scope `feedback:read`.", "tags": [ "Feedback and roadmap" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "description": "Page number, starting at 1.", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page, 1 to 100.", "schema": { "type": "integer", "description": "Rows per page, 1 to 100.", "default": 50, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "description": "Board status slug.", "schema": { "type": "string", "description": "Board status slug.", "example": "planned" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only posts in this category.", "schema": { "type": "integer", "description": "Only posts in this category." } }, { "name": "q", "in": "query", "required": false, "description": "Matches the title or text.", "schema": { "type": "string", "description": "Matches the title or text." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "description": "The page of posts.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Post id." }, "title": { "type": "string", "description": "Title." }, "content": { "type": "string", "description": "What the customer wrote." }, "status": { "type": "string", "description": "Board status slug." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Name." } } }, "vote_count": { "type": "integer", "description": "Votes." }, "comments_count": { "type": "integer", "description": "Comments." }, "on_roadmap": { "type": "boolean", "description": "Whether the post sits on a roadmap column." }, "created_at": { "type": "string", "description": "Posted.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } }, "meta": { "type": "object", "description": "Pagination state.", "properties": { "current_page": { "type": "integer", "description": "Page just returned, starting at 1.", "example": 1 }, "last_page": { "type": "integer", "description": "Last page available for this query.", "example": 4 }, "total": { "type": "integer", "description": "Total rows matching the query.", "example": 187 } } } } }, "example": { "posts": [ { "id": 88, "title": "Dark mode", "content": "Please add a dark theme to the dashboard.", "status": "planned", "category": { "id": 2, "name": "Feature request" }, "vote_count": 41, "comments_count": 6, "on_roadmap": true, "created_at": "2026-09-02T08:30:00Z", "updated_at": "2026-10-01T10:00:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"feedback:read\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "feedback:read" ] } ], "x-klct-scope": "feedback:read" } }, "/roadmap": { "get": { "operationId": "getRoadmap", "summary": "Get the roadmap", "description": "The roadmap columns in display order, each with its posts. Not paginated.\n\nRequires scope `feedback:read`.", "tags": [ "Feedback and roadmap" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "statuses": { "type": "array", "description": "Roadmap columns.", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Column slug." }, "name": { "type": "string", "description": "Column name." }, "color": { "type": "string", "description": "Column color." }, "posts": { "type": "array", "description": "Posts in this column.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Post id." }, "title": { "type": "string", "description": "Title." }, "content": { "type": "string", "description": "What the customer wrote." }, "status": { "type": "string", "description": "Board status slug." }, "category": { "type": "object", "description": "Category, or null.", "properties": { "id": { "type": "integer", "description": "Category id." }, "name": { "type": "string", "description": "Name." } } }, "vote_count": { "type": "integer", "description": "Votes." }, "comments_count": { "type": "integer", "description": "Comments." }, "on_roadmap": { "type": "boolean", "description": "Whether the post sits on a roadmap column." }, "created_at": { "type": "string", "description": "Posted.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Last changed.", "format": "date-time" } } } } } } } } }, "example": { "statuses": [ { "slug": "planned", "name": "Planned", "color": "#6366f1", "posts": [ { "id": 88, "title": "Dark mode", "content": "Please add a dark theme to the dashboard.", "status": "planned", "category": { "id": 2, "name": "Feature request" }, "vote_count": 41, "comments_count": 6, "on_roadmap": true, "created_at": "2026-09-02T08:30:00Z", "updated_at": "2026-10-01T10:00:00Z" } ] } ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"feedback:read\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "feedback:read" ] } ], "x-klct-scope": "feedback:read" } }, "/integrations/sprwt/events": { "post": { "operationId": "sendEvent", "summary": "Forward a product event to start a sequence", "description": "Forwards something that happened in your product (order placed, cart abandoned, subscription renewed) so a matching KLCT sequence can enroll the contact. Contacts created this way are quarantined \"shadow\" contacts unless the account has opted in to exporting real contacts. If `attribution` carries ad parameters and `trigger` is `order_create`, `user_create` or `user_subscriptions_create`, a conversion is recorded for ad optimisation.\n\nRequires scope `sequences:trigger`.", "tags": [ "Events and webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "string", "description": "Event key a sequence trigger listens for.", "example": "order_create" }, "external_ref": { "type": "string", "description": "Your own id for the event, for traceability.", "example": "order_8841" }, "contact": { "type": "object", "description": "Who the event is about.", "properties": { "name": { "type": "string", "description": "First name.", "example": "Dana" }, "last_name": { "type": "string", "description": "Last name." }, "email": { "type": "string", "description": "Email. Either email or phone is required.", "example": "dana@acme.example" }, "phone": { "type": "string", "description": "Phone." } }, "required": [ "name" ] }, "metadata": { "type": "object", "description": "Extra data stored on the contact.", "additionalProperties": true }, "attribution": { "type": "object", "description": "utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid, gclid, klct_ad.", "additionalProperties": true }, "kpi": { "type": "object", "description": "Revenue for purchase events.", "properties": { "value_minor": { "type": "integer", "description": "Order value in minor units (cents).", "example": 4900 }, "currency": { "type": "string", "description": "ISO currency code.", "example": "USD" } } } }, "required": [ "trigger", "contact" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "\"ok\"." }, "enrolled": { "type": "integer", "description": "How many sequences the contact was enrolled in." } } }, "example": { "status": "ok", "enrolled": 1 } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"sequences:trigger\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "sequences:trigger" ] } ], "x-klct-scope": "sequences:trigger" } }, "/oauth-platform/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List your webhook subscriptions", "description": "Only subscriptions created by the calling connection are visible. Requires an OAuth connection, not a manual API key.\n\nRequires scope `webhooks:manage`.", "tags": [ "Events and webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "description": "Subscriptions.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscription id." }, "event_type": { "type": "string", "description": "Event name." }, "target_url": { "type": "string", "description": "Your HTTPS endpoint." }, "is_active": { "type": "boolean", "description": "Whether deliveries are on." }, "created_at": { "type": "string", "description": "Created.", "format": "date-time" } } } } } }, "example": { "webhooks": [ { "id": 7, "event_type": "contact.created", "target_url": "https://acme.example/hooks/klct", "is_active": true, "created_at": "2026-10-01T12:00:00Z" } ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"webhooks:manage\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:manage" ] } ], "x-klct-scope": "webhooks:manage" }, "post": { "operationId": "createWebhook", "summary": "Subscribe to an event", "description": "The `signing_secret` is returned once. Store it; you need it to verify the `X-KLCT-Signature` header. Requires an OAuth connection, not a manual API key.\n\nRequires scope `webhooks:manage`.", "tags": [ "Events and webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "One of the supported events (see the Webhooks guide).", "example": "contact.created" }, "target_url": { "type": "string", "description": "HTTPS URL KLCT will POST to.", "example": "https://acme.example/hooks/klct" } }, "required": [ "event_type", "target_url" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscription id." }, "event_type": { "type": "string", "description": "Event name." }, "target_url": { "type": "string", "description": "Your URL." }, "signing_secret": { "type": "string", "description": "HMAC secret. Shown once." } } }, "example": { "id": 7, "event_type": "contact.created", "target_url": "https://acme.example/hooks/klct", "signing_secret": "3f8c0b6d1e..." } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"webhooks:manage\" scope (error: insufficient_scope).", "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. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:manage" ] } ], "x-klct-scope": "webhooks:manage" } }, "/oauth-platform/webhooks/{webhook}": { "delete": { "operationId": "deleteWebhook", "summary": "Remove a webhook subscription", "description": "Requires scope `webhooks:manage`.", "tags": [ "Events and webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "\"ok\"." } } }, "example": { "status": "ok" } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token does not carry the \"webhooks:manage\" scope (error: insufficient_scope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:manage" ] } ], "x-klct-scope": "webhooks:manage" } }, "/{account}/meetings": { "get": { "operationId": "listMeetings", "summary": "List an account's bookable meetings", "description": "First-party only. Uses the shared machine-to-machine token (`APP_API_TOKEN`) instead of an account key, and is keyed by account id because slugs can be renamed. Account API keys and OAuth tokens are not accepted here.", "tags": [ "Meetings" ], "parameters": [ { "name": "account", "in": "path", "required": true, "description": "KLCT account id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True." }, "account": { "type": "object", "properties": { "id": { "type": "integer", "description": "Account id." }, "name": { "type": "string", "description": "Account name." } } }, "meetings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Meeting type id." }, "name": { "type": "string", "description": "Name." }, "slug": { "type": "string", "description": "URL slug." }, "description": { "type": "string", "description": "Description." }, "duration_minutes": { "type": "integer", "description": "Length." }, "location_type": { "type": "string", "description": "Where it happens (video, phone, in person)." }, "url": { "type": "string", "description": "Public booking URL." } } } } } }, "example": { "ok": true, "account": { "id": 4821, "name": "Acme Dental" }, "meetings": [ { "id": 31, "name": "Intro call", "slug": "intro-call", "description": "15 minutes to talk through your goals.", "duration_minutes": 15, "location_type": "video", "url": "https://app.klctai.com/book/acme/intro-call" } ] } } } }, "401": { "description": "Missing, invalid or expired token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record in this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Retry after the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiToken": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An account API key (Profile, API key) or an OAuth access token. Sent as `Authorization: Bearer `." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization code flow with PKCE (S256). Clients are registered by KLCT.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.klctai.com/oauth/platform/authorize", "tokenUrl": "https://app.klctai.com/oauth/platform/token", "refreshUrl": "https://app.klctai.com/oauth/platform/token", "scopes": { "identity": "No data access by itself — just proves the connection belongs to one specific KLCT account.", "contacts:read": "List and look up this account's contacts.", "contacts:write": "Add new contacts and edit existing ones. Never deletes a contact.", "calls:read": "List calls made or received by this account, with outcome and duration.", "tickets:read": "List and open this account's support tickets and the customer-visible conversation on each. Internal notes are never shown.", "tickets:write": "Open tickets, change their status, priority or due date, add internal notes and send replies to the customer. Never deletes a ticket.", "conversations:read": "List and open this account's live chat conversations and their messages. Internal notes are never shown.", "conversations:write": "Send a team reply into a chat conversation, which hands it to a person, and mark a conversation resolved.", "changelog:read": "List and open this account's changelog entries, drafts included.", "changelog:write": "Create and edit changelog entries, and publish them to the customer portal. Never deletes an entry.", "feedback:read": "List customer feedback posts with their votes and status, and see the public roadmap. Customer names and emails are never included.", "branding:write": "Update this account's logo, colour palette, website and typeface so KLCT emails, pages and social images match the connected platform. Never reads or deletes anything else.", "sequences:trigger": "Forward an event (order placed, cart abandoned, etc.) to enroll a matching contact in a KLCT sequence.", "webhooks:manage": "Register and remove URLs that KLCT calls when an event happens in this account." } } } }, "apiToken": { "type": "http", "scheme": "bearer", "description": "The shared machine-to-machine token (APP_API_TOKEN). Issued by KLCT to first-party integrations only." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Short machine-readable code or a human sentence." }, "error_description": { "type": "string", "description": "Present on OAuth errors." }, "message": { "type": "string", "description": "Present on framework validation errors." }, "errors": { "type": "object", "description": "Field to messages map on validation errors.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "x-webhooks-events": [ "contact.created", "call.completed", "ticket.created", "conversation.message_received", "changelog.published", "feedback.created" ] }