{"openapi":"3.1.0","info":{"title":"Cenaly Public API","version":"1.0.0","description":"Leads (contacts), properties, events, tags, merge, conversations and messages, segments. Create a key in the admin panel: Integrations → API. Limit: 60 requests per minute per key (429 + Retry-After). Every response is an envelope `{meta: {status, requestId, nextCursor?}, data}`; errors — `{meta, error: {code, message?}}`. Writes are applied asynchronously within seconds (`pending: true`). Webhooks (Chat → Settings → Webhooks) deliver conversation events and lead events: lead.created, lead.props_changed, lead.event_tracked, message.goal_reached."},"servers":[{"url":"https://api.cenaly.com/public-api"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Key `cnk_…`. Permissions: contacts:read, contacts:write, events:read, events:write, conversations:read, conversations:write, messages:send, segments:read."}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Meta":{"type":"object","properties":{"status":{"type":"integer"},"requestId":{"type":"string"},"nextCursor":{"type":"string","description":"Present when there is a next page."}}},"Error":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ContactRow":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["anon","lead","user"]},"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"conversations":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"props":{"type":"object","description":"Your custom properties."},"sys":{"type":"object","description":"System `$` properties ($last_seen, $sessions, $initial_utm_source, $revenue…)."},"tags":{"type":"array","items":{"type":"string"}},"events":{"type":"object","description":"Event aggregates: name → {count, first, last}."},"conversations":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"PropOp":{"type":"object","required":["op","key"],"properties":{"op":{"type":"string","enum":["update_or_create","set_once","add","delete","append","union","exclude"]},"key":{"type":"string","description":"Custom property, or `$name` / `$email` / `$phone`."},"value":{}}},"Event":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80,"description":"No dots. `$order_paid`, `$order_refunded` and other `$` names are system events."},"props":{"type":"object","description":"≤ 30 attributes: string ≤ 255, number, boolean, list of strings."},"time":{"description":"ISO-8601 or epoch seconds/ms. Default — now."},"id":{"type":"string","description":"Your idempotency id: the same id twice is counted once."}}},"ConversationRow":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"channel":{"type":"string"},"contactId":{"type":"string"},"assignee":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"unread":{"type":"integer"},"lastMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["incoming","outgoing","bot","note","activity"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time"},"senderName":{"type":"string"},"attachment":{"type":"object","properties":{"url":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"}}}}}}},"paths":{"/v1/me":{"get":{"summary":"The key: permissions, locations, limits","description":"Any valid key.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/locations":{"get":{"summary":"Locations available to the key","description":"Any valid key.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts":{"get":{"summary":"List leads","description":"Permission: `contacts:read`.","x-scope":"contacts:read","parameters":[{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`anon`, `lead`, `user` (comma-separated).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search by name, phone, e-mail.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object","properties":{"total":{"type":"integer"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactRow"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/merge":{"post":{"summary":"Merge two leads (preview without `apply`)","description":"Permission: `contacts:write`. Two leads with different `userId` are never merged (409 `both_user_ids`).","x-scope":"contacts:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["primaryId","secondaryId"],"properties":{"primaryId":{"type":"string"},"secondaryId":{"type":"string"},"apply":{"type":"boolean"},"location":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}":{"get":{"summary":"Get a lead","description":"Permission: `contacts:read`.","x-scope":"contacts:read","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id, or your user id with `by=user_id`.","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"$ref":"#/components/schemas/Contact"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/props":{"post":{"summary":"Change properties with operations","description":"Permission: `contacts:write`. Partial success: `affected`, `notChanged`, `ignored` (with reason). With `by=user_id` an unknown user is created (202).","x-scope":"contacts:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ops":{"type":"array","maxItems":250,"items":{"$ref":"#/components/schemas/PropOp"}},"props":{"type":"object","description":"Shortcut: {key: value} = update_or_create."}}},"example":{"ops":[{"op":"update_or_create","key":"plan","value":"pro"},{"op":"add","key":"orders","value":1},{"op":"union","key":"interests","value":"yoga"}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/tags":{"post":{"summary":"Add tags","description":"Permission: `contacts:write`.","x-scope":"contacts:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}}},"example":{"tags":["vip"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"summary":"Remove tags","description":"Permission: `contacts:write`.","x-scope":"contacts:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"One tag (or `tags` in the body).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/erase":{"post":{"summary":"Erase a lead on the data subject request","description":"Permission: `contacts:write`. Irreversible: card, list row and personal data in conversations.","x-scope":"contacts:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"boolean","const":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/events":{"get":{"summary":"Lead event feed (latest 100)","description":"Permission: `events:read`.","x-scope":"events:read","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Only this event.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Track events for a lead","description":"Permission: `events:write`.","x-scope":"events:write","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Event"}}}},"example":{"events":[{"name":"$order_paid","props":{"$order_id":"A-17","$order_amount":990}}]}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/conversations":{"get":{"summary":"Conversations of a lead","description":"Permission: `conversations:read`.","x-scope":"conversations:read","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/contacts/{id}/messages":{"post":{"summary":"Write to a lead","description":"Permission: `messages:send`. Operator message to the lead’s latest conversation, in its channel (widget, Telegram, WhatsApp, e-mail…). No conversations — 409 `no_conversation`.","x-scope":"messages:send","parameters":[{"name":"id","in":"path","required":true,"description":"Contact id or user id","schema":{"type":"string"}},{"name":"by","in":"query","required":false,"description":"`user_id` — address the lead by YOUR user id (the one signed in identify) instead of the contact id.","schema":{"type":"string","enum":["id","user_id"]}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":4000},"channel":{"type":"string"},"senderName":{"type":"string"}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/events":{"post":{"summary":"Track events in a batch","description":"Permission: `events:write`. Each event addresses `contactId` or your `userId`; an unknown `userId` becomes a new user.","x-scope":"events:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"string"},"events":{"type":"array","maxItems":100,"items":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"contactId":{"type":"string"},"userId":{"type":"string"}}}]}}}},"example":{"events":[{"userId":"42","name":"webinar_registered","props":{"lesson":3}}]}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations":{"get":{"summary":"List conversations (newest activity first)","description":"Permission: `conversations:read`.","x-scope":"conversations:read","parameters":[{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`open`, `pending`, `resolved`, `snoozed`, `bot` (comma-separated).","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"widget, telegram, whatsapp, email, …","schema":{"type":"string"}},{"name":"contactId","in":"query","required":false,"description":"Only this lead.","schema":{"type":"string"}},{"name":"updatedSince","in":"query","required":false,"description":"ISO time.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object","properties":{"total":{"type":"integer"},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationRow"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}":{"get":{"summary":"Get a conversation","description":"Permission: `conversations:read`.","x-scope":"conversations:read","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}/messages":{"get":{"summary":"Messages (newest first)","description":"Permission: `conversations:read`.","x-scope":"conversations:read","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"includeNotes","in":"query","required":false,"description":"`false` — without internal notes.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}/reply":{"post":{"summary":"Reply as an operator or leave a note","description":"Permission: `conversations:write`.","x-scope":"conversations:write","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"type":{"type":"string","enum":["reply","note"]},"senderName":{"type":"string"}}},"example":{"text":"Your order is on the way","type":"reply"}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}/status":{"post":{"summary":"Change status (close = resolved)","description":"Permission: `conversations:write`.","x-scope":"conversations:write","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["open","pending","resolved"]}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}/assign":{"post":{"summary":"Assign an operator (empty — unassign)","description":"Permission: `conversations:write`.","x-scope":"conversations:write","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assignee"],"properties":{"assignee":{"type":"string","description":"Operator e-mail."}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/conversations/{id}/tags":{"post":{"summary":"Add conversation tags","description":"Permission: `conversations:write`.","x-scope":"conversations:write","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"summary":"Remove conversation tags","description":"Permission: `conversations:write`.","x-scope":"conversations:write","parameters":[{"name":"id","in":"path","required":true,"description":"Conversation id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"One tag (or `tags` in the body).","schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/segments":{"get":{"summary":"Saved lead segments","description":"Permission: `segments:read`.","x-scope":"segments:read","parameters":[{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/segments/{id}/contacts":{"get":{"summary":"Members of a segment","description":"Permission: `segments:read`.","x-scope":"segments:read","parameters":[{"name":"id","in":"path","required":true,"description":"Segment id","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Location id or code. Required only when the key covers several locations.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from `meta.nextCursor` of the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–200 (default 50).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"data":{"type":"object","properties":{"total":{"type":"integer"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactRow"}}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}