{ "openapi": "3.1.0", "info": { "title": "PimiDesk API Documentation", "version": "26.10.29", "description": "PimiDesk is an API-first ticket management platform. All routes are prefixed with `/api/v1/`. Authenticate with Bearer tokens via Laravel Sanctum." }, "servers": [ { "url": "https://desk-api.pimi.io/api" } ], "security": [ { "http": [] } ], "paths": { "/v1/users": { "get": { "operationId": "user.getUsers", "tags": [ "Admin — Users" ], "parameters": [ { "name": "search", "in": "query", "description": "Free-text search over name and email.", "schema": { "type": "string" }, "example": "alice" } ], "responses": { "200": { "description": "Paginated set of `User`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/users/{id}": { "get": { "operationId": "user.getUser", "tags": [ "Admin — Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "user.updateUser", "tags": [ "Admin — Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "type": "string", "enum": [ "admin", "customer" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "user.deleteUser", "tags": [ "Admin — Users" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "last_owner" }, "workspaces": { "type": "string" } }, "required": [ "message", "code", "workspaces" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/attachments": { "post": { "operationId": "attachment.store", "tags": [ "Attachments" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 10240 kilobytes." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "original_filename": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "id", "original_filename", "mime_type", "size" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/attachments/{id}": { "get": { "operationId": "attachment.show", "description": "Sends the file as a download. For an image, `variant=preview` returns\nits resized WebP preview instead, or the original when there is none.", "summary": "Download an attachment", "tags": [ "Attachments" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variant", "in": "query", "description": "`preview` returns the resized WebP preview of an image, or the original when there is none.", "schema": { "type": "string" }, "example": "preview" } ], "responses": { "200": { "description": "", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "attachment.destroy", "tags": [ "Attachments" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "This file is attached to a message and cannot be deleted. To remove it from a draft, save the draft without it." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/attachments/{attachment}/inline": { "get": { "operationId": "attachments.inline", "description": "Serves an image embedded in a message, through the signed link the\nmessage body carries, so an `` tag can load it without a token.\nThe link stops working when its viewer can no longer see the\nworkspace, and while the workspace is inactive. A link minted with\n`variant=preview` returns the resized WebP preview of the image, or\nthe original when there is none.", "summary": "Show an inline image", "tags": [ "Attachments" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer" } }, { "name": "u", "in": "query", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "description": "`preview` returns the resized WebP preview of the image, or the original when there is none. It must be part of the signed link.", "schema": { "type": "string" }, "example": "preview" } ], "responses": { "200": { "description": "", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/v1/workspaces/{workspaceId}/attachments/{attachment}/download": { "get": { "operationId": "attachments.download", "description": "The link comes from the MCP `get_attachment` tool and needs no token.\nIt works for 24 hours, and only while its viewer can still see the\nfile and the workspace is active. The file is always sent as a\ndownload.", "summary": "Download an attachment through a signed link", "tags": [ "Attachments" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachment", "in": "path", "required": true, "description": "The attachment ID", "schema": { "type": "integer" } }, { "name": "u", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/v1/email/verify/{id}/{hash}": { "get": { "operationId": "verification.verify", "description": "Completes the confirmation started by the link in the verification email.\nThe `id` and `hash` come from that link and are checked against the signed-in\naccount, so the call must carry the same bearer token as the rest of the API.\nPass the link's query string (`expires`, `signature`) through unchanged.\nCalling it again once the address is confirmed is safe and does nothing.\n\nWhen the account has a `pending_email`, this is the step that applies it:\n`email` becomes the pending address, `email_verified_at` is set and the\npending fields are cleared.", "summary": "Confirm an email address", "tags": [ "Auth & Account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Email verified successfully!" } }, "required": [ "status", "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Email already verified" } }, "required": [ "message" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/email/verification-notification": { "post": { "operationId": "verification.send", "description": "Sends a fresh confirmation link to the address waiting to be confirmed:\nthe account's `pending_email` when it has one, otherwise its `email`.\nAn account can be sent one verification email every five minutes and five\na day, counted together with email changes made through `PUT /v1/account`;\npast that the response is 429. Otherwise responds 200 whether or not a\nmail was sent — read `status` to tell the two apart.", "summary": "Resend the verification email", "tags": [ "Auth & Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Verification link sent" } }, "required": [ "status", "message" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "error" }, "message": { "type": "string", "const": "Email already verified" } }, "required": [ "status", "message" ] } ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "message", "retry_after" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/register": { "post": { "operationId": "account.register", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "One line of text: line breaks and control characters are refused.", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 8, "maxLength": 255 }, "invitation_token": { "type": "string", "maxLength": 100 }, "website": { "type": "string" }, "cf_turnstile_token": { "type": "string" } }, "required": [ "name", "email", "password" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "token": { "type": "string" } }, "required": [ "user", "token" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Registration is currently disabled." } }, "required": [ "message" ] } } } } } } }, "/v1/access-requests": { "post": { "operationId": "accessRequest.store", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Your name, so we know who to address the reply to.", "maxLength": 100 }, "email": { "type": "string", "format": "email", "description": "The address we will reply to with your invitation.", "maxLength": 255 }, "company": { "type": [ "string", "null" ], "description": "The company or team you would use PimiDesk with. Optional.", "maxLength": 100 }, "message": { "type": "string", "description": "A few words on what you want to use PimiDesk for.", "maxLength": 1000 }, "website": { "type": "string" }, "cf_turnstile_token": { "type": "string" } }, "required": [ "name", "email", "message" ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Thanks — we'll be in touch." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/login": { "post": { "operationId": "account.login", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "maxLength": 255 } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "type": "string" }, "token": { "type": "string" } }, "required": [ "user", "token" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Your account has been suspended." } }, "required": [ "message" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Invalid credentials" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/forgot-password": { "post": { "operationId": "passwordReset.forgot", "description": "Emails the account holder a single-use link for choosing a new password.\nThe link is valid for sixty minutes. Both endpoints in this pair are rate\nlimited to five requests per minute. A suspended account gets no link:\nthe answer is a 422 with `code` set to `account_suspended`.", "summary": "Request a password reset link", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The address the account is registered under." } }, "required": [ "email" ] } } } }, "responses": { "422": { "$ref": "#/components/responses/ValidationException" }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Password reset link sent to your email." } }, "required": [ "message" ] } } } } } } }, "/v1/reset-password": { "post": { "operationId": "passwordReset.reset", "description": "Completes the reset started by `POST /v1/forgot-password`. Supply the\ntoken from the emailed link together with the address it was sent to.\nOn success every browser session of the account is signed out, so\nwhoever held the old password is out, and every reply-by-email address\nalready sent to the account stops working. API tokens are not affected.\nA suspended account cannot reset its password, even with a link that was\nsent before the suspension: the answer is a 422 with `code` set to\n`account_suspended`, and the password stays as it was.", "summary": "Set a new password from a reset link", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from the reset link. Single use, expires after sixty minutes." }, "email": { "type": "string", "format": "email", "description": "The address the reset link was sent to." }, "password": { "type": "string", "description": "The new password. Send `password_confirmation` with the same value.", "minLength": 8 }, "password_confirmation": { "type": "string", "minLength": 8 } }, "required": [ "token", "email", "password", "password_confirmation" ] } } } }, "responses": { "422": { "$ref": "#/components/responses/ValidationException" }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Password has been reset successfully." } }, "required": [ "message" ] } } } } } } }, "/v1/account": { "get": { "operationId": "account.getUser", "tags": [ "Auth & Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "pending_email": { "type": [ "string", "null" ] }, "pending_email_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "banned_at": { "type": [ "string", "null" ], "format": "date-time" }, "ban_reason": { "type": [ "string", "null" ] }, "banned_by": { "type": [ "integer", "null" ] }, "plan_id": { "type": [ "integer", "null" ] }, "has_used_trial": { "type": "boolean" }, "max_workspaces": { "type": [ "integer", "null" ] }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "quote_replies": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "gravatar_url": { "type": "string" }, "resolved_display_name": { "type": "string" }, "created_workspaces_count": { "type": "integer", "minimum": 0 }, "eligible_for_trial": { "type": "boolean" }, "subscription_status": { "type": "string", "const": "none" }, "subscription_grace_ends_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "email_verified_at", "pending_email", "pending_email_requested_at", "banned_at", "ban_reason", "banned_by", "plan_id", "has_used_trial", "max_workspaces", "onboarding_completed_at", "quote_replies", "created_at", "updated_at", "display_name", "gravatar_url", "resolved_display_name", "created_workspaces_count", "eligible_for_trial", "subscription_status", "subscription_grace_ends_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "account.updateUser", "description": "Name, password and preferences are saved straight away. A new `email` is\nnot: it is stored as `pending_email`, and `email` and `email_verified_at`\nkeep their current values until the link mailed to the new address is\nopened. Sending a different `email` replaces the pending address; sending\nthe account's current address changes nothing. A throwaway (disposable)\naddress is refused with 422, as it is at registration. API tokens are\nnot affected by an email change.\n\nThe verification email is sent about two minutes after the request, to\nwhichever address is pending at that moment, so several quick corrections\nresult in a single email. An account can be sent one verification email\nevery five minutes and five a day, counted together with\n`POST /v1/email/verification-notification`. While that limit is in effect\na request that changes `email` is answered with 429 and saves nothing.\n\nChanging `password` or sending a new `email` needs `current_password`;\na missing or wrong one is a 422 on that field and nothing is saved.\nAfter five wrong current passwords the check is locked for fifteen\nminutes and answers 429 with `retry_after` (seconds) even for the\nright one.\nRe-sending the account's current (or already pending) address does not.\nA password change signs out every other browser session of the account\nand keeps the one making the request; API tokens are not affected. It\nalso retires every reply-by-email address already sent to the account,\nas `POST /v1/account/reply-addresses/revoke` does.", "summary": "Update the account", "tags": [ "Auth & Account" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "One line of text: line breaks and control characters are refused.", "minLength": 1, "maxLength": 255 }, "display_name": { "type": [ "string", "null" ], "description": "An optional short name shown to your teammates — on notes, mentions\nand assignments — beside `name`. Null or an empty string clears it.\nOne line of text, like `name`. Customers never see it: mail to\nthem keeps `name`.", "maxLength": 255 }, "email": { "type": "string", "format": "email", "description": "A new address is held in `pending_email` until it is confirmed from\nthe verification email sent to it; `email` changes only then.", "maxLength": 255 }, "password": { "type": "string", "minLength": 8, "maxLength": 255 }, "current_password": { "type": [ "string", "null" ], "description": "Required when `password` or a new `email` is sent.", "maxLength": 255 }, "quote_replies": { "type": "boolean", "description": "This user's own starting position for the composer's quote toggle —\nwhether the replies they send bring the thread history along. On\nunless they turn it off." }, "password_confirmation": { "type": "string", "minLength": 8, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "message", "retry_after" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "account.deleteUser", "description": "Needs `current_password` (422 on that field otherwise). Refused with 409\nwhile the account still owns a workspace or is the last owner of one.", "summary": "Delete the account", "tags": [ "Auth & Account" ], "parameters": [ { "name": "current_password", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "last_owner" }, "workspaces": { "type": "string" } }, "required": [ "message", "code", "workspaces" ] }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Delete or transfer the workspaces you own before deleting your account.", "Your account still owns a workspace you no longer have access to. Contact support to delete your account." ] }, "code": { "type": "string", "const": "owns_workspaces" }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "message", "code", "workspaces" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/password": { "put": { "operationId": "account.updatePassword", "description": "Needs the current password; a wrong one is a 422 on `current_password`.\nOn success every other browser session of the account is signed out and\nthe one making the request stays signed in. API tokens are not affected.\nEvery reply-by-email address already sent to the account stops working,\nas with `POST /v1/account/reply-addresses/revoke`.", "summary": "Change the password", "tags": [ "Auth & Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "password": { "type": "string", "minLength": 8, "maxLength": 255 }, "password_confirmation": { "type": "string", "minLength": 8, "maxLength": 255 } }, "required": [ "current_password", "password", "password_confirmation" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Password updated" } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/reply-addresses/revoke": { "post": { "operationId": "account.revokeReplyAddresses", "description": "Notification emails carry a personal Reply-To address: a reply sent to\nit is posted on the thread as you. This stops every such address\nalready sent to you from working, for example when a notification was\nforwarded to someone else. Replies sent to a revoked address are not\nposted and you are emailed to say so. The next notification you receive\ncarries a new address that works. Nothing else about the account\nchanges. Changing or resetting your password does the same.", "summary": "Revoke your reply-by-email addresses", "tags": [ "Auth & Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Reply-by-email addresses revoked" } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/onboarding-complete": { "post": { "operationId": "account.completeOnboarding", "tags": [ "Auth & Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/invitations": { "get": { "operationId": "account.myInvitations", "tags": [ "Auth & Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInvitation" } } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Verify your email address to view and respond to invitations." }, "code": { "type": "string", "const": "email_unverified" } }, "required": [ "message", "code" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/invitations/{token}/accept": { "post": { "operationId": "account.acceptInvitation", "tags": [ "Auth & Account" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Invitation accepted." }, "workspace": { "anyOf": [ { "description": "The workspace you joined. Its `hidden_channels` is your own list\nof hidden sidebar channels, empty for a new member.", "$ref": "#/components/schemas/Workspace" }, { "type": "null" } ] } }, "required": [ "message", "workspace" ] } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "You are already a member of this workspace." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Invitation is invalid or has expired." } }, "required": [ "message" ] } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "This invitation was sent to a different email address." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Verify your email address to view and respond to invitations." }, "code": { "type": "string", "const": "email_unverified" } }, "required": [ "message", "code" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/account/invitations/{token}/decline": { "post": { "operationId": "account.declineInvitation", "tags": [ "Auth & Account" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Invitation declined." } }, "required": [ "message" ] } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "This invitation was sent to a different email address." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Verify your email address to view and respond to invitations." }, "code": { "type": "string", "const": "email_unverified" } }, "required": [ "message", "code" ] } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Invitation is invalid or has expired." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/invitations/{token}": { "get": { "operationId": "account.invitationInfo", "tags": [ "Auth & Account" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string" }, "workspace": { "$ref": "#/components/schemas/Workspace" }, "inviter": { "$ref": "#/components/schemas/User" }, "expires_at": { "type": "string", "format": "date-time" }, "user_exists": { "type": "boolean" } }, "required": [ "email", "role", "workspace", "inviter", "expires_at", "user_exists" ] } }, "required": [ "data" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Invitation is invalid or has expired." } }, "required": [ "message" ] } } } } } } }, "/v1/workspaces/{workspaceId}/automations": { "get": { "operationId": "automation.index", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "automation.store", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`tag` (with `tag_id`) only goes on a `*_tag_added` rule and names the tag whose adding runs it; several `tag` conditions mean any of those tags. `match` applies to the other conditions, which check the first inbound message of the thread.", "enum": [ "from_email", "subject_contains", "body_contains", "contact_list", "tag" ] }, "operator": { "type": [ "string", "null" ], "description": "Not allowed when `type` is `tag`", "enum": [ "equals", "domain", "in", "not_in", null ] }, "value": { "type": [ "string", "null" ], "description": "Required unless `type` is `contact_list` or `tag`", "maxLength": 500 }, "list_id": { "type": [ "integer", "null" ], "description": "Required when `type` is `contact_list`; must belong to this workspace" }, "tag_id": { "type": [ "integer", "null" ], "description": "Required when `type` is `tag`; must belong to this workspace" } }, "required": [ "type" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`move_to_trash` puts the new ticket or conversation straight in the trash: nobody is notified, the sender gets no confirmation email, and no `send_response` goes out for it from any rule that matched the same new mail. A reply already sent is not taken back: when a `*_created` rule replies and adds a tag, and a `*_tag_added` rule for that tag then moves the thread to the trash, the reply has already gone. A `*_created` rule runs only on mail that starts a new ticket or conversation; mail that joins an existing thread runs none. A `*_tag_added` rule trashes an existing thread when one of its tags is added to it. Restore brings a trashed item back. Trash is not kept forever: a trashed item, attachments included, is permanently deleted after the trash retention period (30 days by default), so keep the rule's conditions narrow. Ticket webhooks still fire: a trashed ticket sends `ticket.created` first and `ticket.deleted` last. Conversations send no delete webhook event.", "enum": [ "add_tag", "assign_agent", "send_response", "mark_as_spam", "move_to_trash" ] }, "tag_id": { "type": [ "integer", "null" ], "description": "Required for `add_tag`; must belong to this workspace" }, "user_id": { "type": [ "integer", "null" ], "description": "Required for `assign_agent`; must be a member of this workspace" }, "body": { "type": [ "string", "null" ], "description": "Required for `send_response`" } }, "required": [ "type" ] } }, "stop_on_match": { "type": "boolean" }, "is_active": { "type": "boolean" }, "match": { "description": "How the conditions combine: `all` fires only when every condition passes (AND, the default), `any` fires as soon as one passes (OR).", "$ref": "#/components/schemas/AutomationMatch" }, "event": { "type": "string", "description": "`ticket_created` / `conversation_created` run on a new ticket or conversation opened by inbound email. `ticket_tag_added` / `conversation_tag_added` run when a tag is newly added to a ticket or conversation, by a member, the API, a bulk action or another rule; such a rule needs at least one `tag` condition and cannot use `send_response`. Each tag-added rule runs at most once per thread for one tag added, and rules that add tags set off further rules at most three rounds deep.", "enum": [ "ticket_created", "conversation_created", "ticket_tag_added", "conversation_tag_added" ] } }, "required": [ "name", "conditions", "actions", "event" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Automation" }, { "type": "null" } ] } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Automation limit reached for this workspace." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/automations/reorder": { "patch": { "operationId": "automation.reorder", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "reordered": { "type": "boolean" } }, "required": [ "reordered" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/automations/{id}": { "get": { "operationId": "automation.show", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Automation" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "automation.update", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`tag` (with `tag_id`) only goes on a `*_tag_added` rule and names the tag whose adding runs it; several `tag` conditions mean any of those tags. `match` applies to the other conditions, which check the first inbound message of the thread.", "enum": [ "from_email", "subject_contains", "body_contains", "contact_list", "tag" ] }, "operator": { "type": [ "string", "null" ], "description": "Not allowed when `type` is `tag`", "enum": [ "equals", "domain", "in", "not_in", null ] }, "value": { "type": [ "string", "null" ], "description": "Required unless `type` is `contact_list` or `tag`", "maxLength": 500 }, "list_id": { "type": [ "integer", "null" ], "description": "Required when `type` is `contact_list`; must belong to this workspace" }, "tag_id": { "type": [ "integer", "null" ], "description": "Required when `type` is `tag`; must belong to this workspace" } }, "required": [ "type" ] } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "`move_to_trash` puts the new ticket or conversation straight in the trash: nobody is notified, the sender gets no confirmation email, and no `send_response` goes out for it from any rule that matched the same new mail. A reply already sent is not taken back: when a `*_created` rule replies and adds a tag, and a `*_tag_added` rule for that tag then moves the thread to the trash, the reply has already gone. A `*_created` rule runs only on mail that starts a new ticket or conversation; mail that joins an existing thread runs none. A `*_tag_added` rule trashes an existing thread when one of its tags is added to it. Restore brings a trashed item back. Trash is not kept forever: a trashed item, attachments included, is permanently deleted after the trash retention period (30 days by default), so keep the rule's conditions narrow. Ticket webhooks still fire: a trashed ticket sends `ticket.created` first and `ticket.deleted` last. Conversations send no delete webhook event.", "enum": [ "add_tag", "assign_agent", "send_response", "mark_as_spam", "move_to_trash" ] }, "tag_id": { "type": [ "integer", "null" ], "description": "Required for `add_tag`; must belong to this workspace" }, "user_id": { "type": [ "integer", "null" ], "description": "Required for `assign_agent`; must be a member of this workspace" }, "body": { "type": [ "string", "null" ], "description": "Required for `send_response`" } }, "required": [ "type" ] } }, "stop_on_match": { "type": "boolean" }, "is_active": { "type": "boolean" }, "match": { "description": "How the conditions combine: `all` fires only when every condition passes (AND, the default), `any` fires as soon as one passes (OR).", "$ref": "#/components/schemas/AutomationMatch" }, "event": { "type": "string", "description": "`ticket_created` / `conversation_created` run on a new ticket or conversation opened by inbound email. `ticket_tag_added` / `conversation_tag_added` run when a tag is newly added to a ticket or conversation, by a member, the API, a bulk action or another rule; such a rule needs at least one `tag` condition and cannot use `send_response`. Each tag-added rule runs at most once per thread for one tag added, and rules that add tags set off further rules at most three rounds deep.", "enum": [ "ticket_created", "conversation_created", "ticket_tag_added", "conversation_tag_added" ] } }, "required": [ "name", "conditions", "actions", "event" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Automation" }, { "type": "null" } ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "automation.destroy", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/automations/{id}/test": { "post": { "operationId": "automation.test", "tags": [ "Automation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from_email": { "type": [ "string", "null" ], "maxLength": 255 }, "subject": { "type": [ "string", "null" ], "maxLength": 500 }, "body": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "matched": { "type": "boolean" }, "actions_would_apply": { "type": "array", "items": {} } }, "required": [ "matched", "actions_would_apply" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/blocked-senders": { "get": { "operationId": "blockedSender.index", "tags": [ "Blocked Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the blocked value or the reason.", "schema": { "type": "string" }, "example": "spam@example.com" }, { "name": "status", "in": "query", "description": "`active` (default: every rule still in force), `expired`, or `all`.", "schema": { "type": "string" }, "example": "active" }, { "name": "source", "in": "query", "description": "Only rules added on purpose (`manual`), by marking a thread as spam (`spam_action`), or by the rate-based auto-ban (`auto`).", "schema": { "type": "string" }, "example": "auto" } ], "responses": { "200": { "description": "Paginated set of `BlockedSender`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "blockedSender.store", "tags": [ "Blocked Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The value to block: an address for `exact` (`spammer@example.com`), a domain for `domain` (`example.com` — subdomains included), or a `*`-wildcard for `pattern` (`*@*.example.com`, at least one literal character).", "examples": [ "spammer@example.com" ], "maxLength": 255 }, "match_type": { "anyOf": [ { "description": "`exact` (default), `domain` or `pattern`. Omitted means exact, whatever the value looks like — that is what pre-#108 clients send.", "examples": [ "exact" ], "$ref": "#/components/schemas/BlockMatchType" }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ], "description": "Free text shown next to the rule.", "examples": [ "Rotating addresses on this domain" ], "maxLength": 500 }, "expires_in_hours": { "type": [ "integer", "null" ], "description": "Hours until the rule lifts on its own; omit for a permanent rule.", "examples": [ 24 ], "minimum": 1, "maximum": 8760 } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlockedSender" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only a workspace owner can create a domain or pattern rule." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/blocked-senders/{id}": { "delete": { "operationId": "blockedSender.destroy", "tags": [ "Blocked Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/canned-responses": { "get": { "operationId": "cannedResponse.index", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the canned response name.", "schema": { "type": "string" }, "example": "Refund" } ], "responses": { "200": { "description": "Paginated set of `CannedResponse`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "cannedResponse.store", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "name", "content" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CannedResponse" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Canned response limit reached for your plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/canned-responses/bulk-delete": { "post": { "operationId": "cannedResponse.bulkDelete", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": {} }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/canned-responses/{id}": { "get": { "operationId": "cannedResponse.show", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CannedResponse" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "cannedResponse.update", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CannedResponse" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "cannedResponse.destroy", "tags": [ "Canned Responses" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/oauth/apps": { "get": { "operationId": "oAuthApp.index", "description": "Every app you connected, newest first, with the workspaces it can reach.", "summary": "List connected apps", "tags": [ "Connected Apps" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "client_name": { "type": "string" }, "redirect_host": { "description": "Where the user approved sending the code, not just the client's first URI.", "type": [ "null", "array", "string", "integer", "object" ] }, "scopes": { "type": "array", "items": {} }, "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ] } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Access token use when we have it, else the last refresh." } }, "required": [ "id", "client_name", "redirect_host", "scopes", "workspaces", "created_at", "last_active_at" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/oauth/apps/{id}": { "delete": { "operationId": "oAuthApp.destroy", "description": "Revokes its access token and refresh token. The client has to sign in again.", "summary": "Disconnect an app", "tags": [ "Connected Apps" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-custom-fields": { "get": { "operationId": "contactCustomField.index", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCustomField" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "contactCustomField.store", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean", "url", "email" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 } }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 65535 }, "key": { "type": "string", "description": "Machine key used in `custom_fields` payloads: lowercase letters, digits and underscores.", "pattern": "^[a-z0-9_]+$", "examples": [ "account_manager" ], "maxLength": 255 } }, "required": [ "name", "type", "key" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactCustomField" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-custom-fields/bulk-delete": { "post": { "operationId": "contactCustomField.bulkDelete", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": {} }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-custom-fields/reorder": { "post": { "operationId": "contactCustomField.reorder", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "order" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Order updated." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-custom-fields/{id}": { "get": { "operationId": "contactCustomField.show", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactCustomField" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "contactCustomField.update", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean", "url", "email" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 } }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 65535 }, "key": { "type": "string", "description": "Machine key used in `custom_fields` payloads: lowercase letters, digits and underscores.", "pattern": "^[a-z0-9_]+$", "examples": [ "account_manager" ], "maxLength": 255 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactCustomField" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "contactCustomField.destroy", "tags": [ "Contact Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/{contactId}/lists": { "post": { "operationId": "contactListMembership.addFromContact", "tags": [ "Contact List Membership" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "integer" } }, "required": [ "list_id" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "contact_id": { "type": "integer" }, "list_id": { "type": "integer" } }, "required": [ "contact_id", "list_id" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/{contactId}/lists/{listId}": { "delete": { "operationId": "contactListMembership.removeFromContact", "tags": [ "Contact List Membership" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-lists/{listId}/contacts": { "post": { "operationId": "contactListMembership.bulkAddToList", "tags": [ "Contact List Membership" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "contact_ids" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer" } }, "required": [ "added", "skipped" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "contactListMembership.bulkRemoveFromList", "tags": [ "Contact List Membership" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "removed": { "type": "integer" } }, "required": [ "removed" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-lists/{listId}/contacts/{contactId}": { "delete": { "operationId": "contactListMembership.removeFromList", "tags": [ "Contact List Membership" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "listId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts": { "get": { "operationId": "workspaceContact.index", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "schema": { "type": "string" } }, { "name": "no_organization", "in": "query", "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `organization`, `custom_fields`. Custom field values are only returned when requested here.", "schema": { "type": "string" }, "example": "organization,custom_fields" }, { "name": "status", "in": "query", "description": "Only contacts with this status: `active`, `left`, `bounced` or `do_not_contact`. Comma-separate several, e.g. `left,bounced,do_not_contact` for everyone who cannot be emailed.", "schema": { "type": "string" }, "example": "left,bounced" }, { "name": "external_id", "in": "query", "description": "Return only the contact carrying this `external_id`. Exact match, not a search — use it to look a contact up by your own identifier.", "schema": { "type": "string" }, "example": "cus_ABC123" }, { "name": "search", "in": "query", "description": "Free-text search over the contact's name, email and phone.", "schema": { "type": "string" }, "example": "alice@example.com" } ], "responses": { "200": { "description": "Paginated set of `Contact`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceContact.store", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "timezone": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/ContactStatus" }, "status_reason": { "type": [ "string", "null" ], "maxLength": 255 }, "emails": { "type": "array", "description": "Extra email addresses beside `email`, as `[{email, label}]`, at most 10. Sent, it replaces the whole list (`[]` clears it); left out, the extras stay as they are. Rows with a blank `email` are dropped. `label` is `home`, `office`, `mobile`, `other` or null. An extra equal to the contact's own `email` is refused; one another contact also has is allowed (see `GET /contacts/overlaps`). Incoming mail is matched on the primary `email` only.", "examples": [ [ { "email": "jane@work.example", "label": "office" } ] ], "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "label": { "anyOf": [ { "$ref": "#/components/schemas/ContactExtraLabel" }, { "type": "null" } ] } }, "required": [ "email" ] } }, "phones": { "type": "array", "description": "Extra phone numbers beside `phone`, as `[{phone, label}]`, at most 10, each up to 50 characters. Same rules as `emails`.", "examples": [ [ { "phone": "+1 555 0100", "label": "mobile" } ] ], "items": { "type": "object", "properties": { "phone": { "type": "string", "maxLength": 50 }, "label": { "anyOf": [ { "$ref": "#/components/schemas/ContactExtraLabel" }, { "type": "null" } ] } }, "required": [ "phone" ] } }, "custom_fields": { "type": "object", "description": "Custom field values keyed by field key (see `GET /contact-custom-fields`). Multi-value fields take an array of values. Unknown keys are rejected with 422.", "examples": [ { "region": "EU", "tags": [ "vip", "beta" ] } ], "additionalProperties": {} } }, "required": [ "name", "email" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Contact limit reached for your plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/bulk-delete": { "post": { "operationId": "workspaceContact.bulkDelete", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "affected": {} }, "required": [ "affected" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/overlaps": { "get": { "operationId": "workspaceContact.overlaps", "description": "Every extra email address or phone number that another contact of this workspace also has,\nas primary or extra, grouped by the shared value with the contacts holding it. Emails\ncompare lower-cased and trimmed, phones without spaces, dashes, parentheses and dots (a\nleading `+` counts). Two contacts sharing only a primary are not listed. Groups come newest\nextra first; in a group the primary holder comes first. Read only: nothing is merged.", "summary": "Overlaps: extras another contact also has", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "description": "Only the groups this contact is part of. 404 when the id is not a contact of this workspace.", "schema": { "type": "integer" }, "example": 42 }, { "name": "per_page", "in": "query", "description": "Groups per page, 1–100, default 15.", "schema": { "type": "integer" }, "example": 15 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "email", "phone" ] }, "value": { "type": "string" }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "via": { "type": "string", "enum": [ "primary", "extra" ] }, "label": { "type": [ "string", "null" ] }, "extra_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "name", "email", "phone", "via", "label", "extra_id" ] } } }, "required": [ "kind", "value", "contacts" ] } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "to": { "type": [ "integer", "null" ] }, "path": { "type": "string" }, "first_page_url": { "type": "string" }, "last_page_url": { "type": "string" }, "next_page_url": { "type": [ "string", "null" ] }, "prev_page_url": { "type": [ "string", "null" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } } }, "required": [ "data", "current_page", "last_page", "per_page", "total", "from", "to", "path", "first_page_url", "last_page_url", "next_page_url", "prev_page_url", "links" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/{id}": { "get": { "operationId": "workspaceContact.show", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `organization`, `custom_fields`, `lists`. Custom field values are only returned when requested here.", "schema": { "type": "string" }, "example": "organization,custom_fields,lists" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceContact.update", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "external_id": { "type": [ "string", "null" ], "maxLength": 255 }, "timezone": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/ContactStatus" }, "status_reason": { "type": [ "string", "null" ], "maxLength": 255 }, "emails": { "type": "array", "description": "Extra email addresses beside `email`, as `[{email, label}]`, at most 10. Sent, it replaces the whole list (`[]` clears it); left out, the extras stay as they are. Rows with a blank `email` are dropped. `label` is `home`, `office`, `mobile`, `other` or null. An extra equal to the contact's own `email` is refused; one another contact also has is allowed (see `GET /contacts/overlaps`). Incoming mail is matched on the primary `email` only.", "examples": [ [ { "email": "jane@work.example", "label": "office" } ] ], "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "label": { "anyOf": [ { "$ref": "#/components/schemas/ContactExtraLabel" }, { "type": "null" } ] } }, "required": [ "email" ] } }, "phones": { "type": "array", "description": "Extra phone numbers beside `phone`, as `[{phone, label}]`, at most 10, each up to 50 characters. Same rules as `emails`.", "examples": [ [ { "phone": "+1 555 0100", "label": "mobile" } ] ], "items": { "type": "object", "properties": { "phone": { "type": "string", "maxLength": 50 }, "label": { "anyOf": [ { "$ref": "#/components/schemas/ContactExtraLabel" }, { "type": "null" } ] } }, "required": [ "phone" ] } }, "custom_fields": { "type": "object", "description": "Custom field values keyed by field key (see `GET /contact-custom-fields`). Multi-value fields take an array of values. Unknown keys are rejected with 422.", "examples": [ { "region": "EU", "tags": [ "vip", "beta" ] } ], "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceContact.destroy", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/{id}/emails/{emailId}/make-primary": { "post": { "operationId": "workspaceContact.makePrimaryEmail", "description": "Swaps one of the contact's extra email addresses with its primary `email`: the old primary\ntakes the extra's place, label included. 422 when another contact of the workspace already\nhas that address as its primary `email`.", "summary": "Make an extra email the primary", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "emailId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contacts/{id}/phones/{phoneId}/make-primary": { "post": { "operationId": "workspaceContact.makePrimaryPhone", "description": "Swaps one of the contact's extra phone numbers with its primary `phone`: the old primary\ntakes the extra's place, label included. With no primary phone, the extra simply moves up.", "summary": "Make an extra phone the primary", "tags": [ "Contacts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/activities": { "get": { "operationId": "personalInboxActivity.index", "tags": [ "Conversation Activity" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationActivity`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/activities": { "get": { "operationId": "conversationActivity.index", "tags": [ "Conversation Activity" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationActivity`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/draft": { "get": { "operationId": "conversationDraft.show", "description": "Returns the unsent draft you have saved on this conversation. When you\nhave none, the answer is still 200, with `data` set to `null`; a\nconversation you cannot see is a 404. This route is your own draft only;\non a shared-inbox conversation the list of every draft, your teammates'\nincluded, is `GET …/drafts`.\nThe files the draft holds come back in `attachments`.\n\n`meta.last_inbound_at` is when the other party last wrote on this\nconversation, and `meta.is_stale` is true when that was after the draft was\nlast saved — they added something the draft does not answer yet. Any save\nof the draft clears it, from any client, whether or not that client read\nthe new message first.", "summary": "Get the saved draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/ConversationMessage" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "last_inbound_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_stale": { "type": "boolean", "description": "The cast is for the published schema: Scramble reads `&&` as a string." } }, "required": [ "last_inbound_at", "is_stale" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "null" } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "conversationDraft.upsert", "description": "Saves the reply you are still writing, replacing the draft you already had\non this conversation. Reading the draft back returns the same text you sent\n(an `is_html` draft comes back cleaned, as it will be sent).\n\n`from_email`, `to_email`, `cc_emails` and `attachment_ids` are optional:\nleave a key out to keep what the draft already has, or send it as `null`\nto clear it.", "summary": "Save the draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The reply you are still writing. It is stored exactly as you send\nit — send only your own new text, never the thread history, which\nis added when the reply is sent rather than when it is drafted.\nUp to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML; it is cleaned exactly as a sent\nreply is. Every save sets the format: a save without it stores\nplain text, even over an HTML draft." }, "from_email": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: one on this conversation's side or, on a\nshared-inbox conversation, one of your own personal addresses.\nSending the reply without a `from` uses it while it can still send,\nand falls back to the default if not.", "maxLength": 255 }, "to_email": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Sending the reply without a `to` uses this\naddress; a `to` on the send wins over it.", "maxLength": 255 }, "cc_emails": { "type": [ "array", "null" ], "description": "Kept with the draft so your composer can show it again. Sending\ndoes not use it: pass the list as `cc` on the reply itself.", "items": { "type": "string", "format": "email", "maxLength": 255 } }, "attachment_ids": { "type": [ "array", "null" ], "description": "Files the draft holds, as ids from the attachment upload endpoint:\nthe complete list each time. An id you leave out is let go and can\nbe used elsewhere. Each file must be in this workspace and not\nalready attached to another message or draft. Sending the reply\nsends these files with it.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "conversationDraft.destroy", "description": "Deletes your own unsent draft on this conversation. Publishing a draft as a\nreply clears it too, so this is only needed to abandon one. Files the draft\nheld are let go, not deleted straight away.", "summary": "Discard the draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/drafts": { "get": { "operationId": "conversationDrafts.index", "description": "The unsent drafts on this shared-inbox conversation, yours and your\nteammates', least recently saved first. Each row carries its `author`\n(`id`, `name`, `display_name`, `resolved_display_name`), `is_mine`, the\nfull `body` and a plain-text `preview`, `is_html`, `from_email`,\n`to_email`, `cc_emails` and the files it holds in `attachments`, which\ndownload through the attachment endpoint like any other file on the\nconversation.\n\n`last_inbound_at` is when the other party last wrote. `replied_since`\nis true on a teammate's draft when a member has sent a reply on the\nconversation since it was saved, and `is_stale` is true when either the\nother party wrote again or `replied_since` is.\n\nShared inbox only: a personal-inbox conversation is a 404 here, and its\ndrafts are never shown to anyone but their author. A teammate's draft is\nread-only, and a draft whose author is no longer a member of the\nworkspace is not listed.", "summary": "List every draft on the conversation", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "resolved_display_name": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "display_name", "resolved_display_name" ] }, "is_mine": { "type": "boolean" }, "body": { "type": [ "string", "null" ] }, "is_html": { "type": "boolean" }, "preview": { "type": "string" }, "from_email": { "type": [ "string", "null" ] }, "to_email": { "type": [ "string", "null" ] }, "cc_emails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "original_filename": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size": { "type": "integer" } }, "required": [ "id", "original_filename", "mime_type", "size" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_inbound_at": { "type": [ "string", "null" ] }, "replied_since": { "type": "boolean" }, "is_stale": { "type": "boolean" } }, "required": [ "id", "author", "is_mine", "body", "is_html", "preview", "from_email", "to_email", "cc_emails", "attachments", "created_at", "updated_at", "last_inbound_at", "replied_since", "is_stale" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/drafts/{draftId}": { "delete": { "operationId": "conversationDrafts.discard", "description": "Deletes one draft on this shared-inbox conversation: your own, or, for a\nworkspace owner, a teammate's. Any other member gets a 403 on a draft\nthat is not theirs. Files the draft held are let go, not deleted straight\naway, and discarding a teammate's draft adds a `draft_discarded` entry to\nthe conversation's activity naming whose it was.", "summary": "Discard a draft by id", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Only the author or a workspace owner can discard this draft." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "The shared inbox is disabled for this workspace." } }, "required": [ "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/draft": { "get": { "operationId": "personalInboxDraft.show", "description": "Returns the unsent draft you have saved on this conversation. When you\nhave none, the answer is still 200, with `data` set to `null`; a\nconversation you cannot see is a 404. This route is your own draft only;\non a shared-inbox conversation the list of every draft, your teammates'\nincluded, is `GET …/drafts`.\nThe files the draft holds come back in `attachments`.\n\n`meta.last_inbound_at` is when the other party last wrote on this\nconversation, and `meta.is_stale` is true when that was after the draft was\nlast saved — they added something the draft does not answer yet. Any save\nof the draft clears it, from any client, whether or not that client read\nthe new message first.", "summary": "Get the saved draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/ConversationMessage" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "last_inbound_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_stale": { "type": "boolean", "description": "The cast is for the published schema: Scramble reads `&&` as a string." } }, "required": [ "last_inbound_at", "is_stale" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "null" } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "personalInboxDraft.upsert", "description": "Saves the reply you are still writing, replacing the draft you already had\non this conversation. Reading the draft back returns the same text you sent\n(an `is_html` draft comes back cleaned, as it will be sent).\n\n`from_email`, `to_email`, `cc_emails` and `attachment_ids` are optional:\nleave a key out to keep what the draft already has, or send it as `null`\nto clear it.", "summary": "Save the draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The reply you are still writing. It is stored exactly as you send\nit — send only your own new text, never the thread history, which\nis added when the reply is sent rather than when it is drafted.\nUp to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML; it is cleaned exactly as a sent\nreply is. Every save sets the format: a save without it stores\nplain text, even over an HTML draft." }, "from_email": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: one on this conversation's side or, on a\nshared-inbox conversation, one of your own personal addresses.\nSending the reply without a `from` uses it while it can still send,\nand falls back to the default if not.", "maxLength": 255 }, "to_email": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Sending the reply without a `to` uses this\naddress; a `to` on the send wins over it.", "maxLength": 255 }, "cc_emails": { "type": [ "array", "null" ], "description": "Kept with the draft so your composer can show it again. Sending\ndoes not use it: pass the list as `cc` on the reply itself.", "items": { "type": "string", "format": "email", "maxLength": 255 } }, "attachment_ids": { "type": [ "array", "null" ], "description": "Files the draft holds, as ids from the attachment upload endpoint:\nthe complete list each time. An id you leave out is let go and can\nbe used elsewhere. Each file must be in this workspace and not\nalready attached to another message or draft. Sending the reply\nsends these files with it.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "personalInboxDraft.destroy", "description": "Deletes your own unsent draft on this conversation. Publishing a draft as a\nreply clears it too, so this is only needed to abandon one. Files the draft\nheld are let go, not deleted straight away.", "summary": "Discard the draft reply", "tags": [ "Conversation Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{parentId}/github-links": { "get": { "operationId": "personalInboxGithubLink.index", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GithubLink" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "personalInboxGithubLink.store", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GithubLink" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{parentId}/github-links/{id}": { "delete": { "operationId": "personalInboxGithubLink.destroy", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{parentId}/github-links": { "get": { "operationId": "conversationGithubLink.index", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GithubLink" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "conversationGithubLink.store", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GithubLink" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{parentId}/github-links/{id}": { "delete": { "operationId": "conversationGithubLink.destroy", "tags": [ "Conversation Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{parentId}/links": { "get": { "operationId": "personalInboxLink.index", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "personalInboxLink.store", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 }, "title": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Link" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{parentId}/links/{id}": { "delete": { "operationId": "personalInboxLink.destroy", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{parentId}/links": { "get": { "operationId": "conversationLink.index", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "conversationLink.store", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 }, "title": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Link" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{parentId}/links/{id}": { "delete": { "operationId": "conversationLink.destroy", "tags": [ "Conversation Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages/trashed": { "get": { "operationId": "personalInboxMessage.trashed", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages": { "get": { "operationId": "personalInboxMessage.index", "description": "The messages of one shared-inbox or personal-inbox conversation, a page at\na time. Messages come back oldest first (`created_at`, then `id`), so\nwalking every page returns each message exactly once, in thread order.\nEach row is shaped exactly like the messages embedded in the conversation's\n`show` response, with `sender` and `attachments` loaded. Drafts and deleted\nmessages are not listed. Listing does not mark the conversation read.\n\nEach message row also carries:\n- `text` — plain-text *new content* of the message (HTML flattened, quoted\n history / forwarded chain / signature / legal footer removed). Prefer it\n over the full body for reading, summarising and search.\n- `is_auto_reply` — true for inbound auto-responders (out-of-office,\n mailer-daemon, …) that threaded onto this thread. Such rows do not reopen\n the thread, bump activity or notify agents; skip them when deciding what\n the customer last said.\n- `is_html` — whether the full `body` is HTML (true only for a body that\n arrived as an email's HTML part; everything authored in PimiDesk is plain\n text).\n- `images_trusted` — true when the From address is one of the workspace's\n trusted senders (`GET …/trusted-senders`), so a client may load the\n message's external images without asking. Never true for mail that\n failed DMARC or was accepted without proof of its From.", "summary": "List conversation messages", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "personalInboxMessage.store", "description": "Posts either an outbound reply (delivered by email) or an internal note. A\nreply does not need the caller to paste the thread history into the body: the\nmessage to be quoted is recorded when the reply is created (returned as\n`quote_source_message_id`) and the quote itself is rendered while the email is\nbeing built, so the stored body is only what the agent wrote.\n\nTo send only the files you list, whatever your saved draft holds, pass\n`attachments_exact: true` with `attachment_ids`.\n\nIf you have a saved draft on this conversation, an outbound reply replaces it\nand is stamped with the time you send it. Without a `to`, the reply goes to the\ndraft's `to_email` when it has one; a `to` sent as null or an empty string\nignores it and uses the thread's own reply address. Files attached to your draft go out with the\nreply; `attachment_ids` may name them again or add more, up to 10 in all. An\ninternal note leaves your draft alone.\n\nAn outbound reply with nobody to send to (no `to`, no drafted recipient and\nno earlier message on the conversation naming one) is refused with a 422 on\n`to`; nothing is saved and your draft is kept.", "summary": "Create a conversation message", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "What you are saying now, and only that: the thread history is\nattached to the outgoing email for you, so a body that repeats it\nreaches the contact with the conversation quoted twice. Up to\n10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved:\nparagraphs, line breaks, bold, italic, underline, lists, quotes,\ncode and http(s)/mailto links are kept, everything else is removed\n(the text inside unknown tags stays). Links are kept as plain text\nwhile the workspace is on a trial. Left out or false, `body` is\nplain text and any angle brackets in it are shown as typed." }, "attachments_exact": { "type": "boolean", "description": "Send true to make `attachment_ids` the complete list of files on this reply. Any file your saved draft holds that is not listed is taken off the draft before it is sent; it becomes an unused upload again and is removed a day later. With `attachment_ids` left out, null or empty, the reply then carries no files. Left out or false, every file on your draft goes out, plus the ones listed. Has no effect on an internal note, which never uses the draft." }, "type": { "type": "string", "enum": [ "outbound", "internal_note" ] }, "include_quote": { "type": "boolean", "description": "Controls whether the outgoing email carries the thread history. Left\nat its default of true, the preceding message is attached as a quote\n(a collapsible blockquote in the HTML part, `> ` prefixed lines in the\nplain-text one). Pass false for an unquoted reply. Notes ignore it." }, "from": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: an inbox address that can send on this\nconversation's side or, on a shared-inbox conversation, one of your\nown personal addresses (the customer's answer to it still lands on\nthis conversation). Left out, it is the From saved on your draft\nwhen that address can still send, else the address the latest\ncustomer message arrived on, else the address the last reply on\nthis conversation was sent from, else the address the\nconversation was opened on, else the first sendable inbox address.\nYour own address is only a default once you have replied from it\non this conversation. An address that cannot send is skipped at\nevery step.", "maxLength": 255 }, "to": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Left out, it is the recipient saved on your\ndraft, else the latest customer message's Reply-To or sender. A\n`to` you pass always wins over the draft's; pass it as null or an\nempty string to ignore the draft's and reply where the thread\nalready goes. On a trial workspace a\ndrafted address that is not already on the thread is refused with\n403, exactly like one passed here.", "maxLength": 255 }, "cc": { "type": "array", "description": "The CC list of this reply, and the only one used: CC addresses\nsaved on your draft are not carried over, so pass them here again.", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it such a reply is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "attachment_ids": { "type": [ "array", "null" ], "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet, or are on your saved draft. Any other id refuses the\nwhole request with a 422 on `attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 }, "mentioned_user_ids": { "type": "array", "description": "Members to notify about an internal note in the shared inbox. Each\none gets an email with the note, unless they wrote it or have\nswitched mention emails off. Ignored on an outbound reply, and\nrefused with a 422 on a personal inbox thread, whose notes only\nits owner can read, and on a conversation in the trash. At most\n50 members.", "items": { "type": "integer", "description": "Every id must belong to a member of this workspace, once; any\nother id is rejected." }, "maxItems": 50, "uniqueItems": true } }, "required": [ "body", "type" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages/{messageId}/restore": { "post": { "operationId": "personalInboxMessage.restore", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages/{messageId}/raw": { "get": { "operationId": "personalInboxMessage.rawPayload", "description": "Returns the stored raw email (RFC 822 / MIME source) of an inbound\nmessage as `text/plain`. Pass `download=1` to receive it as a\n`message/rfc822` attachment named `.eml` instead.\n\n404 when the message did not arrive by email or its stored source is\nno longer available.", "summary": "View the original email", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "description": "Set to `1` to receive the source as a `message/rfc822` attachment download named `.eml` instead of inline text.", "schema": { "type": "boolean" }, "example": 1 } ], "responses": { "200": { "description": "The stored raw email source.", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "message/rfc822": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "schema": { "type": "string", "enum": [ "chunked" ] } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Content-Disposition": { "schema": { "type": "string" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file is empty" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file not found on disk" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "No raw payload available for this message" } }, "required": [ "message" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages/{messageId}/force": { "delete": { "operationId": "personalInboxMessage.forceDestroy", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/messages/{messageId}": { "delete": { "operationId": "personalInboxMessage.destroy", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The first message of a conversation cannot be deleted." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages/trashed": { "get": { "operationId": "conversationMessage.trashed", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages": { "get": { "operationId": "conversationMessage.index", "description": "The messages of one shared-inbox or personal-inbox conversation, a page at\na time. Messages come back oldest first (`created_at`, then `id`), so\nwalking every page returns each message exactly once, in thread order.\nEach row is shaped exactly like the messages embedded in the conversation's\n`show` response, with `sender` and `attachments` loaded. Drafts and deleted\nmessages are not listed. Listing does not mark the conversation read.\n\nEach message row also carries:\n- `text` — plain-text *new content* of the message (HTML flattened, quoted\n history / forwarded chain / signature / legal footer removed). Prefer it\n over the full body for reading, summarising and search.\n- `is_auto_reply` — true for inbound auto-responders (out-of-office,\n mailer-daemon, …) that threaded onto this thread. Such rows do not reopen\n the thread, bump activity or notify agents; skip them when deciding what\n the customer last said.\n- `is_html` — whether the full `body` is HTML (true only for a body that\n arrived as an email's HTML part; everything authored in PimiDesk is plain\n text).\n- `images_trusted` — true when the From address is one of the workspace's\n trusted senders (`GET …/trusted-senders`), so a client may load the\n message's external images without asking. Never true for mail that\n failed DMARC or was accepted without proof of its From.", "summary": "List conversation messages", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ConversationMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "conversationMessage.store", "description": "Posts either an outbound reply (delivered by email) or an internal note. A\nreply does not need the caller to paste the thread history into the body: the\nmessage to be quoted is recorded when the reply is created (returned as\n`quote_source_message_id`) and the quote itself is rendered while the email is\nbeing built, so the stored body is only what the agent wrote.\n\nTo send only the files you list, whatever your saved draft holds, pass\n`attachments_exact: true` with `attachment_ids`.\n\nIf you have a saved draft on this conversation, an outbound reply replaces it\nand is stamped with the time you send it. Without a `to`, the reply goes to the\ndraft's `to_email` when it has one; a `to` sent as null or an empty string\nignores it and uses the thread's own reply address. Files attached to your draft go out with the\nreply; `attachment_ids` may name them again or add more, up to 10 in all. An\ninternal note leaves your draft alone.\n\nAn outbound reply with nobody to send to (no `to`, no drafted recipient and\nno earlier message on the conversation naming one) is refused with a 422 on\n`to`; nothing is saved and your draft is kept.", "summary": "Create a conversation message", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "What you are saying now, and only that: the thread history is\nattached to the outgoing email for you, so a body that repeats it\nreaches the contact with the conversation quoted twice. Up to\n10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved:\nparagraphs, line breaks, bold, italic, underline, lists, quotes,\ncode and http(s)/mailto links are kept, everything else is removed\n(the text inside unknown tags stays). Links are kept as plain text\nwhile the workspace is on a trial. Left out or false, `body` is\nplain text and any angle brackets in it are shown as typed." }, "attachments_exact": { "type": "boolean", "description": "Send true to make `attachment_ids` the complete list of files on this reply. Any file your saved draft holds that is not listed is taken off the draft before it is sent; it becomes an unused upload again and is removed a day later. With `attachment_ids` left out, null or empty, the reply then carries no files. Left out or false, every file on your draft goes out, plus the ones listed. Has no effect on an internal note, which never uses the draft." }, "type": { "type": "string", "enum": [ "outbound", "internal_note" ] }, "include_quote": { "type": "boolean", "description": "Controls whether the outgoing email carries the thread history. Left\nat its default of true, the preceding message is attached as a quote\n(a collapsible blockquote in the HTML part, `> ` prefixed lines in the\nplain-text one). Pass false for an unquoted reply. Notes ignore it." }, "from": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: an inbox address that can send on this\nconversation's side or, on a shared-inbox conversation, one of your\nown personal addresses (the customer's answer to it still lands on\nthis conversation). Left out, it is the From saved on your draft\nwhen that address can still send, else the address the latest\ncustomer message arrived on, else the address the last reply on\nthis conversation was sent from, else the address the\nconversation was opened on, else the first sendable inbox address.\nYour own address is only a default once you have replied from it\non this conversation. An address that cannot send is skipped at\nevery step.", "maxLength": 255 }, "to": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Left out, it is the recipient saved on your\ndraft, else the latest customer message's Reply-To or sender. A\n`to` you pass always wins over the draft's; pass it as null or an\nempty string to ignore the draft's and reply where the thread\nalready goes. On a trial workspace a\ndrafted address that is not already on the thread is refused with\n403, exactly like one passed here.", "maxLength": 255 }, "cc": { "type": "array", "description": "The CC list of this reply, and the only one used: CC addresses\nsaved on your draft are not carried over, so pass them here again.", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it such a reply is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "attachment_ids": { "type": [ "array", "null" ], "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet, or are on your saved draft. Any other id refuses the\nwhole request with a 422 on `attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 }, "mentioned_user_ids": { "type": "array", "description": "Members to notify about an internal note in the shared inbox. Each\none gets an email with the note, unless they wrote it or have\nswitched mention emails off. Ignored on an outbound reply, and\nrefused with a 422 on a personal inbox thread, whose notes only\nits owner can read, and on a conversation in the trash. At most\n50 members.", "items": { "type": "integer", "description": "Every id must belong to a member of this workspace, once; any\nother id is rejected." }, "maxItems": 50, "uniqueItems": true } }, "required": [ "body", "type" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}/restore": { "post": { "operationId": "conversationMessage.restore", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}/raw": { "get": { "operationId": "conversationMessage.rawPayload", "description": "Returns the stored raw email (RFC 822 / MIME source) of an inbound\nmessage as `text/plain`. Pass `download=1` to receive it as a\n`message/rfc822` attachment named `.eml` instead.\n\n404 when the message did not arrive by email or its stored source is\nno longer available.", "summary": "View the original email", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "description": "Set to `1` to receive the source as a `message/rfc822` attachment download named `.eml` instead of inline text.", "schema": { "type": "boolean" }, "example": 1 } ], "responses": { "200": { "description": "The stored raw email source.", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "message/rfc822": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "schema": { "type": "string", "enum": [ "chunked" ] } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Content-Disposition": { "schema": { "type": "string" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file is empty" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file not found on disk" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "No raw payload available for this message" } }, "required": [ "message" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}/force": { "delete": { "operationId": "conversationMessage.forceDestroy", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}": { "delete": { "operationId": "conversationMessage.destroy", "tags": [ "Conversation Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The first message of a conversation cannot be deleted." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{parentId}/summary": { "get": { "operationId": "conversationSummary.show", "description": "Besides the stored columns, the response carries `is_stale` and `messages_since`\n(messages the summary does not cover), `body_html` (the Markdown rendered: raw\nHTML escaped, images left out, links opening in a new tab) and\n`updated_by {id, name}`. Works on a trashed thread too.", "summary": "Get the thread's summary", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "conversationSummary.upsert", "description": "Plain Markdown, at most 1,000 characters, no HTML tags or entities. The\nheadline is derived from the first line. `covers_message_id` moves to the\nthread's newest message, so a fresh write is never stale. `replaced` says\nwhether an earlier summary was overwritten. A trashed thread answers 404.", "summary": "Write the thread's summary (create or replace)", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 1000 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "conversationSummary.destroy", "summary": "Remove the thread's summary. A trashed thread answers 404", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{parentId}/summary": { "get": { "operationId": "personalInboxSummary.show", "description": "Besides the stored columns, the response carries `is_stale` and `messages_since`\n(messages the summary does not cover), `body_html` (the Markdown rendered: raw\nHTML escaped, images left out, links opening in a new tab) and\n`updated_by {id, name}`. Works on a trashed thread too.", "summary": "Get the thread's summary", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "personalInboxSummary.upsert", "description": "Plain Markdown, at most 1,000 characters, no HTML tags or entities. The\nheadline is derived from the first line. `covers_message_id` moves to the\nthread's newest message, so a fresh write is never stale. `replaced` says\nwhether an earlier summary was overwritten. A trashed thread answers 404.", "summary": "Write the thread's summary (create or replace)", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 1000 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "personalInboxSummary.destroy", "summary": "Remove the thread's summary. A trashed thread answers 404", "tags": [ "Conversation Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/tags": { "get": { "operationId": "personalInboxTag.index", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "personalInboxTag.store", "description": "`data` is the tag. A new tag can start `conversation_tag_added` automation rules, which run\nbefore this responds; `meta.thread` says what the conversation looks like after them:\n`trashed` and `is_spam`, and `automations`, the rules this add set off in run order\n(`id`, `name`, and the action types each applied, e.g. `move_to_trash`,\n`mark_as_spam`, `add_tag`, `assign_agent`). `trashed` is also true for a conversation\nthat was in the trash before; `automations` is then empty.", "summary": "Add a tag to the conversation, by `tag_id` or by `tag_name` (created when missing)", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "integer" }, "tag_name": { "type": "string", "minLength": 1, "maxLength": 255 } } } } } }, "responses": { "201": { "description": "The tag, and the conversation after any tag-added rules (`meta.thread`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "meta": { "type": "object", "properties": { "thread": { "type": "object", "properties": { "trashed": { "type": "boolean" }, "is_spam": { "type": "boolean" }, "automations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "actions" ] } } }, "required": [ "trashed", "is_spam", "automations" ] } }, "required": [ "thread" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag limit reached for your plan." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{conversationId}/tags/{tagId}": { "delete": { "operationId": "personalInboxTag.destroy", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag is not attached to this conversation." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/tags": { "get": { "operationId": "conversationTag.index", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "conversationTag.store", "description": "`data` is the tag. A new tag can start `conversation_tag_added` automation rules, which run\nbefore this responds; `meta.thread` says what the conversation looks like after them:\n`trashed` and `is_spam`, and `automations`, the rules this add set off in run order\n(`id`, `name`, and the action types each applied, e.g. `move_to_trash`,\n`mark_as_spam`, `add_tag`, `assign_agent`). `trashed` is also true for a conversation\nthat was in the trash before; `automations` is then empty.", "summary": "Add a tag to the conversation, by `tag_id` or by `tag_name` (created when missing)", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "integer" }, "tag_name": { "type": "string", "minLength": 1, "maxLength": 255 } } } } } }, "responses": { "201": { "description": "The tag, and the conversation after any tag-added rules (`meta.thread`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "meta": { "type": "object", "properties": { "thread": { "type": "object", "properties": { "trashed": { "type": "boolean" }, "is_spam": { "type": "boolean" }, "automations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "actions" ] } } }, "required": [ "trashed", "is_spam", "automations" ] } }, "required": [ "thread" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag limit reached for your plan." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{conversationId}/tags/{tagId}": { "delete": { "operationId": "conversationTag.destroy", "tags": [ "Conversation Tag" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag is not attached to this conversation." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/trashed": { "get": { "operationId": "conversation.trashed", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over subject, sender address, message bodies (the quote-stripped new content only — quoted history never matches) and the contact's name / email / phone. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched, or null when the hit was on subject / contact. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "Paginated set of `Conversation`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/bulk": { "post": { "operationId": "conversation.bulkAction", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 }, "action": { "type": "string", "enum": [ "trash", "spam", "not_spam", "restore", "force_delete", "assign", "unassign", "close", "reopen", "archive", "unarchive", "mark_read", "mark_unread", "add_tag", "remove_tag" ] }, "agent_id": { "type": [ "integer", "null" ] }, "tag_id": { "type": [ "integer", "null" ] } }, "required": [ "ids", "action" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "affected": { "type": "string" }, "still_blocked": { "type": "string" } }, "required": [ "affected", "still_blocked" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations": { "get": { "operationId": "conversation.index", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "tag", "in": "query", "description": "Only conversations carrying the tag with this name. The whole name must match; upper and lower case are treated the same.", "schema": { "type": [ "string", "null" ] } }, { "name": "waiting_on", "in": "query", "description": "Reply state: `us` — the contact answered a message of yours and is waiting on a reply; `customer` — you wrote last and are waiting on them; `none` — nobody (closed or spam, marked \"no reply needed\", or mail you have not answered). New inbound mail does not start as `us`: a conversation waits on you only after a reply of yours, or when a member marks it. Spam, automatic replies and mail whose sender could not be verified never do.", "schema": { "type": [ "string", "null" ], "enum": [ "us", "customer", "none", null ] } }, { "name": "sort", "in": "query", "description": "`latest` (default): most recent activity first. `waiting_on_since`: longest-waiting first, threads nobody is waiting on last.", "schema": { "type": [ "string", "null" ], "enum": [ "latest", "waiting_on_since", null ] } }, { "name": "is_spam", "in": "query", "description": "Spam filtering: default excludes spam, ?is_spam=1 shows only spam, ?is_spam=all shows everything", "schema": { "type": "string" } }, { "name": "spam_reason", "in": "query", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Archive filtering: default excludes archived, ?archived=1 shows only archived, ?archived=all shows everything", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_read", "in": "query", "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include on top of the always-loaded `contact`, `agent` and first message: `tags`, `github_links`, `links` (every reference link, GitHub ones included), `summary` (the thread summary: `headline` and `is_stale` only).", "schema": { "type": "string" }, "example": "tags,github_links" }, { "name": "search", "in": "query", "description": "Free-text search over subject, sender address, message bodies (the quote-stripped new content only — quoted history never matches) and the contact's name / email / phone. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched, or null when the hit was on subject / contact. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "Paginated set of `Conversation`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "conversation.store", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email", "maxLength": 255 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it the message is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "body": { "type": "string", "description": "Up to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved:\nparagraphs, line breaks, bold, italic, underline, lists, quotes,\ncode and http(s)/mailto links are kept, everything else is removed\n(the text inside unknown tags stays). Left out or false, `body` is\nplain text and any angle brackets in it are shown as typed." }, "workspace_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "attachment_ids": { "type": "array", "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet. Any other id refuses the whole request with a 422 on\n`attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "to", "subject", "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Trial workspaces can only reply to incoming email. Start by sending a message to your workspace address — once a customer emails you, you can reply to that thread. This lifts as soon as your trial converts to a paid plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/spam": { "delete": { "operationId": "conversation.deleteAllSpam", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}": { "get": { "operationId": "conversation.show", "description": "`messages` holds the newest 50 messages of the thread, oldest first.\n`messages_limit` picks another number, 0 to 100; 0 leaves them out. A\nlonger thread is not embedded whole: read it a page at a time from\n`GET …/{id}/messages`. `meta.messages` says what was embedded: `total`\nmessages in the thread, how many were `returned`, the `limit` applied,\n`truncated` (true when older messages were left out) and `url`, the\npaged list that holds the whole thread.\n\nEach message row also carries:\n- `text` — plain-text *new content* of the message (HTML flattened, quoted\n history / forwarded chain / signature / legal footer removed). Prefer it\n over the full body for reading, summarising and search.\n- `is_auto_reply` — true for inbound auto-responders (out-of-office,\n mailer-daemon, …) that threaded onto this thread. Such rows do not reopen\n the thread, bump activity or notify agents; skip them when deciding what\n the customer last said.\n- `is_html` — whether the full `body` is HTML: a body that arrived as an\n email's HTML part, or a message posted with `is_html: true`. Everything\n else is plain text.\n\nOpening a conversation marks it read — except with a read-only token,\nwhich leaves `is_read` as it was.", "summary": "Show a shared-inbox conversation with its newest messages", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messages_limit", "in": "query", "description": "How many of the newest messages to embed, 0 to 100. Default 50, also when sent empty. 0 embeds none.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "with", "in": "query", "description": "Comma-separated extras to include: `drafts` (every unsent draft on the conversation, your teammates' included; the rows of `GET …/conversations/{id}/drafts`).", "schema": { "type": "string" }, "example": "drafts" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "meta": { "type": "object", "properties": { "messages": { "type": "object", "properties": { "total": { "type": "integer" }, "returned": { "type": "integer" }, "limit": { "type": "integer" }, "truncated": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "total", "returned", "limit", "truncated", "url" ] } }, "required": [ "messages" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "conversation.update", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "is_read": { "type": "boolean" }, "waiting_on": { "type": [ "string", "null" ], "description": "Override the reply state: `us`, `customer`, or null for \"no reply needed\" (an empty string is refused). The next customer message or reply of yours moves it again. A closed or spam thread has no reply state, so `us` and `customer` are refused there.", "enum": [ "us", "customer", null ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "conversation.destroy", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/mark-spam": { "post": { "operationId": "conversation.markSpam", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/not-spam": { "post": { "operationId": "conversation.notSpam", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The sender is still blocked by a wider rule." }, "data": { "type": "string" }, "still_blocked": { "type": "string" } }, "required": [ "message", "data", "still_blocked" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/archive": { "post": { "operationId": "conversation.archive", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/unarchive": { "post": { "operationId": "conversation.unarchive", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/answered-externally": { "post": { "operationId": "conversation.answeredExternally", "description": "Records that a member already answered outside PimiDesk — from their own mailbox without\ncopying the inbox, by phone, on chat. The conversation waits on the customer, and an\n`answered_externally` activity row keeps the note; the customer's next message puts it back\non you. Nothing is sent, and status, read state and archive state are left as they are.\nRepeating the latest mark with the same note changes nothing. A closed or spam conversation\nhas no reply state and is refused with 422: reopen it, or mark it not spam, first.", "summary": "Mark a conversation answered externally", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Where and when the answer went, kept on the activity row (\"Called them back on 22 Sep\"). Optional.", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/restore": { "post": { "operationId": "conversation.restore", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/conversations/{id}/force": { "delete": { "operationId": "conversation.forceDestroy", "tags": [ "Conversations (Shared Inbox)" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/domains": { "get": { "operationId": "workspaceDomain.index", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the domain name.", "schema": { "type": "string" }, "example": "example.com" } ], "responses": { "200": { "description": "Paginated set of `WorkspaceDomain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceDomain.store", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 255 }, "provider": { "type": [ "string", "null" ], "enum": [ "ses", null ] } }, "required": [ "domain" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "domain": { "type": "string" }, "provider": { "type": "string" }, "aws_region": { "type": [ "string", "null" ] }, "provider_metadata": { "type": [ "array", "null" ], "items": {} }, "mx_verified": { "type": "boolean" }, "send_verified": { "type": "boolean" }, "verification_token": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "ownership_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "ownership_missing_count": { "type": "integer" }, "ownership_drifted_at": { "type": [ "string", "null" ], "format": "date-time" }, "mail_from_missing_count": { "type": "integer" }, "mail_from_drifted_at": { "type": [ "string", "null" ], "format": "date-time" }, "mx_missing_count": { "type": "integer" }, "mx_drifted_at": { "type": [ "string", "null" ], "format": "date-time" }, "dkim_missing_count": { "type": "integer" }, "dkim_drifted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_count": { "type": "integer" }, "bounce_count": { "type": "integer" }, "last_bounce_at": { "type": [ "string", "null" ], "format": "date-time" }, "complaint_count": { "type": "integer" }, "last_complaint_at": { "type": [ "string", "null" ], "format": "date-time" }, "ses_status": { "type": [ "string", "null" ] }, "drifted_records": { "type": "array", "items": {} }, "dns_records": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "domain", "provider", "aws_region", "provider_metadata", "mx_verified", "send_verified", "verification_token", "verified_at", "ownership_verified_at", "ownership_missing_count", "ownership_drifted_at", "mail_from_missing_count", "mail_from_drifted_at", "mx_missing_count", "mx_drifted_at", "dkim_missing_count", "dkim_drifted_at", "created_at", "updated_at", "sent_count", "bounce_count", "last_bounce_at", "complaint_count", "last_complaint_at", "ses_status", "drifted_records", "dns_records" ] }, "dns_records": { "type": "object", "properties": { "sending_dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "receiving_dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_dns_record": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "valid": { "type": [ "boolean", "null" ] } }, "required": [ "type", "name", "value", "purpose", "valid" ] }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } } }, "required": [ "sending_dns_records", "receiving_dns_records", "dmarc_dns_record", "dns_records" ] } }, "required": [ "domain", "dns_records" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Domain limit reached for your plan." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/domains/{id}": { "get": { "operationId": "workspaceDomain.show", "description": "Besides the grouped DNS records, the detail carries `dmarc_alignment`:\nwhat the DMARC aggregate reports received for this domain over the last\n30 days say about it. Sending sources are split into `aligned_sources`\n(every message passed DMARC) and `failing_sources` (some did not), each\nwith message counts; each list holds at most the 50 busiest sources and\n`truncated` is true when either was cut, while the totals always cover\nevery source. A source carries `unauthenticated_reporter: true`\nwhen at least one of the reports mentioning it came from a reporter\nwhose own mail did not pass DMARC — such reports still count, but their\ncontent cannot be verified. `ready_to_tighten` is true once the window\nis clean and deep enough to move the published policy up one step\n(`tighten_to`); otherwise `tighten_reason` says what is still missing.\nThe field is null until the domain is verified. Reports are matched on\nthe exact domain name, so a subdomain never sees its parent's reports.", "summary": "Get a domain", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "domain": { "type": "string" }, "provider": { "type": "string" }, "aws_region": { "type": [ "string", "null" ] }, "provider_metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "mx_verified": { "type": "boolean" }, "send_verified": { "type": "boolean" }, "verification_token": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "ownership_verified_at": { "type": [ "string", "null" ] }, "ownership_missing_count": { "type": "integer" }, "ownership_drifted_at": { "type": [ "string", "null" ] }, "dkim_missing_count": { "type": "integer" }, "dkim_drifted_at": { "type": [ "string", "null" ] }, "mx_missing_count": { "type": "integer" }, "mx_drifted_at": { "type": [ "string", "null" ] }, "mail_from_missing_count": { "type": "integer" }, "mail_from_drifted_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "sent_count": { "type": "integer" }, "bounce_count": { "type": "integer" }, "last_bounce_at": { "type": [ "string", "null" ] }, "complaint_count": { "type": "integer" }, "last_complaint_at": { "type": [ "string", "null" ] }, "ses_status": { "type": [ "string", "null" ] }, "drifted_records": { "type": "array", "items": { "type": "string" } }, "sending_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "receiving_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_dns_record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "valid": { "type": [ "boolean", "null" ] } }, "required": [ "type", "name", "value", "purpose", "valid" ] }, "dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_alignment": { "type": [ "object", "null" ], "properties": { "window_days": { "type": "integer" }, "reports": { "type": "integer" }, "report_days": { "type": "integer" }, "unauthenticated_reports": { "type": "integer" }, "first_seen": { "type": [ "string", "null" ] }, "last_seen": { "type": [ "string", "null" ] }, "policy": { "type": [ "string", "null" ] }, "messages": { "type": "integer" }, "aligned": { "type": "integer" }, "failing": { "type": "integer" }, "aligned_sources": { "type": "array", "items": { "type": "object", "properties": { "source_ip": { "type": "string" }, "messages": { "type": "integer" }, "aligned": { "type": "integer" }, "failing": { "type": "integer" }, "dkim_aligned": { "type": "integer" }, "spf_aligned": { "type": "integer" }, "last_seen": { "type": "string" }, "unauthenticated_reporter": { "type": "boolean" } }, "required": [ "source_ip", "messages", "aligned", "failing", "dkim_aligned", "spf_aligned", "last_seen", "unauthenticated_reporter" ] } }, "failing_sources": { "type": "array", "items": { "type": "object", "properties": { "source_ip": { "type": "string" }, "messages": { "type": "integer" }, "aligned": { "type": "integer" }, "failing": { "type": "integer" }, "dkim_aligned": { "type": "integer" }, "spf_aligned": { "type": "integer" }, "last_seen": { "type": "string" }, "unauthenticated_reporter": { "type": "boolean" } }, "required": [ "source_ip", "messages", "aligned", "failing", "dkim_aligned", "spf_aligned", "last_seen", "unauthenticated_reporter" ] } }, "truncated": { "type": "boolean" }, "ready_to_tighten": { "type": "boolean" }, "tighten_to": { "type": [ "string", "null" ] }, "tighten_reason": { "type": [ "string", "null" ] } }, "required": [ "window_days", "reports", "report_days", "unauthenticated_reports", "first_seen", "last_seen", "policy", "messages", "aligned", "failing", "aligned_sources", "failing_sources", "truncated", "ready_to_tighten", "tighten_to", "tighten_reason" ] } }, "required": [ "id", "workspace_id", "domain", "provider", "aws_region", "provider_metadata", "mx_verified", "send_verified", "verification_token", "verified_at", "ownership_verified_at", "ownership_missing_count", "ownership_drifted_at", "dkim_missing_count", "dkim_drifted_at", "mx_missing_count", "mx_drifted_at", "mail_from_missing_count", "mail_from_drifted_at", "created_at", "updated_at", "sent_count", "bounce_count", "last_bounce_at", "complaint_count", "last_complaint_at", "ses_status", "drifted_records", "sending_dns_records", "receiving_dns_records", "dmarc_dns_record", "dns_records", "dmarc_alignment" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceDomain.destroy", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purge_ses", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "No content" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/domains/{id}/dns-records": { "get": { "operationId": "workspaceDomain.dnsRecords", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sending_dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "receiving_dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_dns_record": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "valid": { "type": [ "boolean", "null" ] } }, "required": [ "type", "name", "value", "purpose", "valid" ] }, "dns_records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } } }, "required": [ "sending_dns_records", "receiving_dns_records", "dmarc_dns_record", "dns_records" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/domains/{id}/verify-ownership": { "post": { "operationId": "workspaceDomain.verifyOwnership", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "422": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "No verification token found for this domain." } }, "required": [ "message" ] } ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "domain": { "type": "string" }, "provider": { "type": "string" }, "aws_region": { "type": [ "string", "null" ] }, "provider_metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "mx_verified": { "type": "boolean" }, "send_verified": { "type": "boolean" }, "verification_token": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "ownership_verified_at": { "type": [ "string", "null" ] }, "ownership_missing_count": { "type": "integer" }, "ownership_drifted_at": { "type": [ "string", "null" ] }, "dkim_missing_count": { "type": "integer" }, "dkim_drifted_at": { "type": [ "string", "null" ] }, "mx_missing_count": { "type": "integer" }, "mx_drifted_at": { "type": [ "string", "null" ] }, "mail_from_missing_count": { "type": "integer" }, "mail_from_drifted_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "sent_count": { "type": "integer" }, "bounce_count": { "type": "integer" }, "last_bounce_at": { "type": [ "string", "null" ] }, "complaint_count": { "type": "integer" }, "last_complaint_at": { "type": [ "string", "null" ] }, "ses_status": { "type": [ "string", "null" ] }, "drifted_records": { "type": "array", "items": { "type": "string" } }, "sending_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "receiving_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_dns_record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "valid": { "type": [ "boolean", "null" ] } }, "required": [ "type", "name", "value", "purpose", "valid" ] }, "dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } } }, "required": [ "id", "workspace_id", "domain", "provider", "aws_region", "provider_metadata", "mx_verified", "send_verified", "verification_token", "verified_at", "ownership_verified_at", "ownership_missing_count", "ownership_drifted_at", "dkim_missing_count", "dkim_drifted_at", "mx_missing_count", "mx_drifted_at", "mail_from_missing_count", "mail_from_drifted_at", "created_at", "updated_at", "sent_count", "bounce_count", "last_bounce_at", "complaint_count", "last_complaint_at", "ses_status", "drifted_records", "sending_dns_records", "receiving_dns_records", "dmarc_dns_record", "dns_records" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/domains/{id}/verify": { "post": { "operationId": "workspaceDomain.verify", "tags": [ "Custom Domains" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "domain": { "type": "string" }, "provider": { "type": "string" }, "aws_region": { "type": [ "string", "null" ] }, "provider_metadata": { "type": [ "object", "null" ], "additionalProperties": {} }, "mx_verified": { "type": "boolean" }, "send_verified": { "type": "boolean" }, "verification_token": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "ownership_verified_at": { "type": [ "string", "null" ] }, "ownership_missing_count": { "type": "integer" }, "ownership_drifted_at": { "type": [ "string", "null" ] }, "dkim_missing_count": { "type": "integer" }, "dkim_drifted_at": { "type": [ "string", "null" ] }, "mx_missing_count": { "type": "integer" }, "mx_drifted_at": { "type": [ "string", "null" ] }, "mail_from_missing_count": { "type": "integer" }, "mail_from_drifted_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "sent_count": { "type": "integer" }, "bounce_count": { "type": "integer" }, "last_bounce_at": { "type": [ "string", "null" ] }, "complaint_count": { "type": "integer" }, "last_complaint_at": { "type": [ "string", "null" ] }, "ses_status": { "type": [ "string", "null" ] }, "drifted_records": { "type": "array", "items": { "type": "string" } }, "sending_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "receiving_dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } }, "dmarc_dns_record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" }, "valid": { "type": [ "boolean", "null" ] } }, "required": [ "type", "name", "value", "purpose", "valid" ] }, "dns_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "type", "name", "value", "purpose" ] } } }, "required": [ "id", "workspace_id", "domain", "provider", "aws_region", "provider_metadata", "mx_verified", "send_verified", "verification_token", "verified_at", "ownership_verified_at", "ownership_missing_count", "ownership_drifted_at", "dkim_missing_count", "dkim_drifted_at", "mx_missing_count", "mx_drifted_at", "mail_from_missing_count", "mail_from_drifted_at", "created_at", "updated_at", "sent_count", "bounce_count", "last_bounce_at", "complaint_count", "last_complaint_at", "ses_status", "drifted_records", "sending_dns_records", "receiving_dns_records", "dmarc_dns_record", "dns_records" ] } }, "required": [ "data" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/drafts": { "get": { "operationId": "workspaceDraft.index", "description": "Every unsent draft you have saved in this workspace, across tickets, the\nshared inbox and your own personal inbox, most recently saved first. Drafts\non threads in the trash are left out until the thread is restored.\n\n`scope=team` adds your teammates' drafts on tickets and shared-inbox\nconversations. A personal-inbox draft is only ever your own. Each row names\nits `author` (`id`, `name`, `display_name`, `resolved_display_name`) and\nsays whether it `is_mine`.\n\nEach row names its `channel` (`ticket`, `conversation` for the shared inbox,\n`personal_inbox`, or `new_email`) and `thread_id`, so the draft can be opened\nthrough that thread's own draft endpoint. `preview` is the draft as plain\ntext, cut to 140 characters. `last_inbound_at` is when the customer last\nwrote on the thread, and `is_stale` is true when that was after the draft\nwas last saved. On a teammate's draft `replied_since` is true when a member\nhas sent a reply on the thread since it was saved, and that makes it\n`is_stale` too.\n\nA `new_email` row is a draft of a new email, which has no thread yet:\n`thread_id` is null, `id` is the draft's id on `…/email-drafts/{id}`,\n`inbox` says whether it will go from the `shared` or your `personal`\ninbox, and `contact_email` is its `to`. They are always your own, never\nadded by `scope=team`, and never stale. Every other row has `inbox` null.", "summary": "List your drafts", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "description": "Only this channel: `ticket`, `conversation` (shared inbox), `personal_inbox` or `new_email` (drafts of new emails). Leave it out for all four.", "schema": { "type": "string" }, "example": "ticket" }, { "name": "scope", "in": "query", "description": "`mine` (the default) lists your drafts. `team` adds your teammates' drafts on tickets and the shared inbox.", "schema": { "type": "string" }, "example": "team" }, { "name": "per_page", "in": "query", "description": "Rows per page, at most 100.", "schema": { "type": "integer" }, "example": 15 }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "resolved_display_name": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "display_name", "resolved_display_name" ] }, "is_mine": { "type": "boolean" }, "channel": { "type": "string" }, "inbox": { "type": [ "string", "null" ] }, "thread_id": { "type": [ "integer", "null" ] }, "subject": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "preview": { "type": "string" }, "is_html": { "type": "boolean" }, "to_email": { "type": [ "string", "null" ] }, "cc_emails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "attachments_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_inbound_at": { "type": [ "string", "null" ] }, "is_stale": { "type": "boolean" }, "replied_since": { "type": "boolean" }, "thread_status": { "type": [ "string", "null" ] }, "thread_is_spam": { "type": "boolean" }, "thread_archived_at": { "type": [ "string", "null" ] } }, "required": [ "id", "author", "is_mine", "channel", "inbox", "thread_id", "subject", "contact_name", "contact_email", "preview", "is_html", "to_email", "cc_emails", "attachments_count", "created_at", "updated_at", "last_inbound_at", "is_stale", "replied_since", "thread_status", "thread_is_spam", "thread_archived_at" ] } }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "from": { "type": [ "integer", "null" ] }, "to": { "type": [ "integer", "null" ] }, "path": { "type": "string" }, "first_page_url": { "type": "string" }, "last_page_url": { "type": "string" }, "next_page_url": { "type": [ "string", "null" ] }, "prev_page_url": { "type": [ "string", "null" ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } } }, "required": [ "data", "current_page", "last_page", "per_page", "total", "from", "to", "path", "first_page_url", "last_page_url", "next_page_url", "prev_page_url", "links" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/drafts/count": { "get": { "operationId": "workspaceDraft.count", "description": "How many drafts of your own the list above holds across all enabled\nchannels, drafts of new emails included — the number for a sidebar\nbadge, without loading the drafts themselves. Teammates' drafts are\nnever counted.", "summary": "Count your drafts", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/email-drafts": { "get": { "operationId": "emailDrafts.index", "description": "The drafts of new emails you have saved in this workspace, most\nrecently saved first. Only your own: nobody else's are listed, a\nworkspace owner's included. A draft for an inbox that is turned off is\nleft out until it is turned on again. Each draft carries the files it\nholds in `attachments`.", "summary": "List your email drafts", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Rows per page, at most 100.", "schema": { "type": "integer" }, "example": 15 }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Paginated set of `EmailDraft`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "emailDrafts.store", "description": "Saves a new email you are still writing, without sending anything.\nOnly `channel` is required: a draft can be saved empty and filled in\nby later saves. Nothing about the recipient is checked or created until\nthe draft is sent — contact status, limits and the contact itself are\nthe send's.\n\nRefused with a 403 on a trial workspace, which cannot start a new\nthread at all, and when the channel's inbox is turned off. A\n`from_email` that cannot send from that inbox is a 422 that names the\naddresses that can. A member keeps at most 100 email drafts per\nworkspace; the next save is a 422.", "summary": "Save a new email draft", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "description": "`shared` sends from the team's shared inbox, `personal` from your own personal inbox. Fixed once the draft is saved.", "enum": [ "shared", "personal" ] }, "from_email": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: an inbox address that can send from the draft's inbox — a shared one for `shared`, one of your own for `personal`. Left empty, the inbox's first sendable address is used when the draft is sent.", "maxLength": 255 }, "to": { "type": [ "string", "null" ], "format": "email", "description": "The one recipient. Not needed to save; needed to send.", "maxLength": 255 }, "cc": { "type": [ "array", "null" ], "description": "Addresses to copy, at most 5.", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 5 }, "subject": { "type": [ "string", "null" ], "description": "Up to 255 characters. Not needed to save; needed to send.", "maxLength": 255 }, "body": { "type": [ "string", "null" ], "description": "The email's text: up to 10,000 characters of plain text, or 40,000 with `is_html`. Not needed to save; needed to send.", "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved, as a composed email is: paragraphs, line breaks, bold, italic, underline, lists, quotes, code and http(s)/mailto links are kept, everything else is removed. Left out or false, `body` is plain text. Only read together with `body`." }, "attachment_ids": { "type": [ "array", "null" ], "description": "Files the draft holds, as ids from the attachment upload endpoint, at most 10: the complete list each time. An id you leave out is let go. Each file must be one you uploaded to this workspace and not attached to anything else. Sending the draft sends these files.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "channel" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailDraft" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/email-drafts/{id}": { "get": { "operationId": "emailDrafts.show", "description": "One of your own email drafts, with the files it holds in\n`attachments`. Another member's draft is a 404, as a missing one is.", "summary": "Get an email draft", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailDraft" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "emailDrafts.update", "description": "Saves the email you are still writing over the draft. Every field is\noptional: leave a key out to keep what the draft already has, or send\nit as `null` to clear it (`attachment_ids` as `null` or `[]` lets every\nfile go). `channel` cannot change. `is_html` describes `body` and is\nonly read with it: a save that sends `body` without `is_html` stores\nplain text.", "summary": "Update an email draft", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from_email": { "type": [ "string", "null" ], "format": "email", "description": "The address to send from: an inbox address that can send from the draft's inbox — a shared one for `shared`, one of your own for `personal`. Left empty, the inbox's first sendable address is used when the draft is sent.", "maxLength": 255 }, "to": { "type": [ "string", "null" ], "format": "email", "description": "The one recipient. Not needed to save; needed to send.", "maxLength": 255 }, "cc": { "type": [ "array", "null" ], "description": "Addresses to copy, at most 5.", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 5 }, "subject": { "type": [ "string", "null" ], "description": "Up to 255 characters. Not needed to save; needed to send.", "maxLength": 255 }, "body": { "type": [ "string", "null" ], "description": "The email's text: up to 10,000 characters of plain text, or 40,000 with `is_html`. Not needed to save; needed to send.", "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved, as a composed email is: paragraphs, line breaks, bold, italic, underline, lists, quotes, code and http(s)/mailto links are kept, everything else is removed. Left out or false, `body` is plain text. Only read together with `body`." }, "attachment_ids": { "type": [ "array", "null" ], "description": "Files the draft holds, as ids from the attachment upload endpoint, at most 10: the complete list each time. An id you leave out is let go. Each file must be one you uploaded to this workspace and not attached to anything else. Sending the draft sends these files.", "items": { "type": "integer" }, "maxItems": 10 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmailDraft" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "emailDrafts.destroy", "description": "Deletes one of your own email drafts. Files it held are let go, not\ndeleted straight away: they can be attached elsewhere, and unused ones\nare cleared away after a day. A draft that has just been sent is\nalready gone: a 404. This works while the draft's inbox is turned\noff, too.", "summary": "Discard an email draft", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/email-drafts/{id}/send": { "post": { "operationId": "emailDrafts.send", "description": "Sends the draft as a new email and deletes it: the same as\n`POST …/conversations` (channel `shared`) or `POST …/personal-inbox`\n(channel `personal`) with the draft's fields, and the same answer — the\nnew conversation with its first message. The draft's files go out with\nit. A draft without a recipient, a subject or any text is a 422 on\n`to`, `subject` or `body`, and nothing is sent.\n\nEverything compose checks is checked here, when the email is sent: a\ntrial workspace is refused, the `from_email` must still be able to send\nfrom the draft's inbox (refused, never swapped; without one the\ninbox's first sendable address is used), and a recipient whose contact\nis marked left, bounced or do-not-contact is refused unless `force` is\ntrue. A `from_email` that can no longer send is a 422 on `from_email`\nnaming the addresses that can. When the workspace has a contact limit\nset and `to` is a new contact past it, the answer is a 429. Sending\ntwice is safe: the second call finds the draft gone, a 404, and no\nsecond email goes out.", "summary": "Send an email draft", "tags": [ "Drafts" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it the email is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Trial workspaces can only reply to incoming email. Start by sending a message to your workspace address — once a customer emails you, you can reply to that thread. This lifts as soon as your trial converts to a paid plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/notification-preferences": { "get": { "operationId": "notificationPreference.index", "description": "Your email notification settings for this workspace, one key per\nnotification type, each `true` (on) or `false` (off). Every type is\nlisted, including ones you have never changed, so this is the full set\nof types you can turn on or off.", "summary": "List your notification settings", "tags": [ "Notification Preferences" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "notificationPreference.update", "description": "Returns the full set of settings after the update, in the same shape as\nthe list endpoint.", "summary": "Update your notification settings", "tags": [ "Notification Preferences" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket_assigned": { "type": "boolean" }, "ticket_reply": { "type": "boolean" }, "conversation_message": { "type": "boolean" }, "ticket_status_changed": { "type": "boolean" }, "sla_breach": { "type": "boolean" }, "mentioned": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/unsubscribe": { "post": { "operationId": "notificationPreference.unsubscribe", "tags": [ "Notification Preferences" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "number" }, "workspace_id": { "type": "number" }, "type": { "type": "string" }, "token": { "type": "string" } }, "required": [ "user_id", "workspace_id", "type", "token" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "You have been unsubscribed from this notification type." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Invalid or expired unsubscribe link." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/workspaces/{workspaceId}/organization-custom-fields": { "get": { "operationId": "organizationCustomField.index", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationCustomField" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "organizationCustomField.store", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean", "url", "email" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 }, "maxItems": 200 }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 65535 }, "key": { "type": "string", "description": "Machine key used in `custom_fields` payloads: lowercase letters, digits and underscores.", "pattern": "^[a-z0-9_]+$", "examples": [ "account_tier" ], "maxLength": 255 } }, "required": [ "name", "type", "key" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrganizationCustomField" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organization-custom-fields/bulk-delete": { "post": { "operationId": "organizationCustomField.bulkDelete", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": {} }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organization-custom-fields/reorder": { "post": { "operationId": "organizationCustomField.reorder", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "array", "description": "Field ids in the order they should appear; at most one per definition.", "items": { "type": "integer" }, "minItems": 1, "maxItems": 50 } }, "required": [ "order" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Order updated." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organization-custom-fields/{id}": { "get": { "operationId": "organizationCustomField.show", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrganizationCustomField" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "organizationCustomField.update", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "text", "number", "date", "select", "boolean", "url", "email" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 }, "maxItems": 200 }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 65535 }, "key": { "type": "string", "description": "Machine key used in `custom_fields` payloads: lowercase letters, digits and underscores.", "pattern": "^[a-z0-9_]+$", "examples": [ "account_tier" ], "maxLength": 255 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OrganizationCustomField" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "organizationCustomField.destroy", "tags": [ "Organization Custom Field" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organizations": { "get": { "operationId": "workspaceOrganization.index", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contacts`, `custom_fields`. On the list, custom field values are only returned when requested here.", "schema": { "type": "string" }, "example": "contacts,custom_fields" }, { "name": "search", "in": "query", "description": "Free-text search over the organization name.", "schema": { "type": "string" }, "example": "Acme" } ], "responses": { "200": { "description": "Paginated set of `Organization`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceOrganization.store", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "custom_fields": { "type": "object", "description": "Custom field values keyed by field key (see `GET /organization-custom-fields`). Multi-value fields take an array of at most 50 values, each given once. Unknown keys are rejected with 422.", "examples": [ { "website": "https://acme.example", "regions": [ "EU", "US" ] } ], "additionalProperties": {} } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organizations/bulk-delete": { "post": { "operationId": "workspaceOrganization.bulkDelete", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": {} }, "required": [ "deleted" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/organizations/{id}": { "get": { "operationId": "workspaceOrganization.show", "description": "The organization with its custom field values under `custom_fields`,\nkeyed by field key (a multi-value field is a list). No `with` is needed\nfor them.", "summary": "Show an organization", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contacts`. Custom field values are always returned here.", "schema": { "type": "string" }, "example": "contacts" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceOrganization.update", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "custom_fields": { "type": "object", "description": "Custom field values keyed by field key (see `GET /organization-custom-fields`). Only the fields you name change; null clears one. Multi-value fields take an array of at most 50 values, each given once. Unknown keys are rejected with 422.", "examples": [ { "website": "https://acme.example", "regions": [ "EU", "US" ] } ], "additionalProperties": {} } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceOrganization.destroy", "tags": [ "Organizations" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/paddle-webhook": { "post": { "operationId": "paddleWebhook", "summary": "Handle a Paddle webhook call", "tags": [ "Paddle Webhook" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/tokens": { "get": { "operationId": "token.index", "tags": [ "Personal Access Tokens" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "abilities": { "description": "`['*']` = full access (every login-session and pre-scoping\ntoken, incl. rows with NULL abilities); otherwise `read`,\n`read` + `draft`, or `read` + `write`.", "anyOf": [ { "type": "array" }, { "type": "array", "prefixItems": [ { "type": "string", "const": "*" } ], "minItems": 1, "maxItems": 1 } ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_current": { "type": "boolean" } }, "required": [ "id", "name", "abilities", "last_used_at", "created_at", "is_current" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "token.store", "description": "Scoped tokens: pass `abilities` to restrict the token. `read`\nallows GET requests only; `write` allows everything and is stored as\n`[\"read\", \"write\"]`. `draft` is stored as `[\"read\", \"draft\"]` and is meant\nfor an AI assistant connected to the MCP server that should prepare\nreplies for a person to send: over this REST API it is read-only, and\nover MCP it can also save drafts, add internal notes and change a\nticket's tags, priority or assignee, but never send a reply, create a\nticket or change a status. Changing tags includes creating a tag by\nname, and assigning a ticket notifies the member it is assigned to. A\nnote can mention teammates, who are then emailed (at most 5 mentions\nof the same teammate per hour are emailed). Omit `abilities` (or pass `[\"*\"]`) for a\nfull-access token, which behaves exactly like tokens issued before\nscoping existed. A request outside the token's abilities gets 403.\nAvailable on every plan.", "summary": "Create an API token", "tags": [ "Personal Access Tokens" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "abilities": { "type": "array", "description": "Any of `read`, `draft`, `write`, `*`. `write` and `draft` imply `read`; `write` wins over `draft`; `*` (the default when omitted) is full access. `draft` is read-only on the REST API and, over MCP, may write drafts, notes (a note that mentions teammates emails them) and a ticket's tags (creating a tag by name), priority or assignee (the new assignee is notified), but never send to a customer.", "examples": [ [ "read" ] ], "items": { "type": "string", "enum": [ "read", "draft", "write", "*" ] } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abilities": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "abilities", "created_at" ] }, "plain_text_token": { "type": "string" } }, "required": [ "data", "plain_text_token" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/tokens/{id}/rotate": { "post": { "operationId": "token.rotate", "description": "Replaces a token with a fresh one in a single call. The replacement keeps\nthe old token's name, abilities and expiry, and the old value stops working\nimmediately. The response is the same as creating a token, including a new\n`plain_text_token` shown only this once.\n\nUnlike `DELETE /tokens/{id}`, this accepts the token the request itself\nauthenticated with. That is the point: the token you most need to retire —\none that has leaked into a log or a transcript — is often the only\ncredential you hold.\n\nThe old value is revoked before the response is sent, so store the new\n`plain_text_token` before making any other request. Both writes happen in\none database transaction with the old row locked, so two concurrent\nrotations of the same token cannot both succeed, and a rotation that races\na delete of the same token returns 404 rather than reviving it.\n\nRotation mints a token, so it follows the same rule as creating one: a\n`read`-only token gets 403, including when rotating itself. Rotate it with\nanother of your tokens that has `write`. Session tokens and tokens\nbelonging to another account return 404. Takes no request body.", "summary": "Rotate an API token", "tags": [ "Personal Access Tokens" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abilities": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "abilities", "created_at" ] }, "plain_text_token": { "type": "string" } }, "required": [ "data", "plain_text_token" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/tokens/{id}": { "delete": { "operationId": "token.destroy", "tags": [ "Personal Access Tokens" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cannot revoke the token currently in use. Rotate it instead: POST /tokens/{id}/rotate." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/trashed": { "get": { "operationId": "personalInbox.trashed", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over subject, sender address, message bodies (the quote-stripped new content only — quoted history never matches) and the contact's name / email / phone. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched, or null when the hit was on subject / contact. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "`LengthAwarePaginator`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LengthAwarePaginator" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/bulk": { "post": { "operationId": "personalInbox.bulkAction", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 }, "action": { "type": "string", "enum": [ "trash", "spam", "not_spam", "restore", "force_delete", "close", "reopen", "archive", "unarchive", "mark_read", "mark_unread", "add_tag", "remove_tag" ] }, "tag_id": { "type": [ "integer", "null" ] } }, "required": [ "ids", "action" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "affected": { "type": "string" }, "still_blocked": { "type": "string" } }, "required": [ "affected", "still_blocked" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox": { "get": { "operationId": "personalInbox.index", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "tag", "in": "query", "description": "Only conversations carrying the tag with this name. The whole name must match; upper and lower case are treated the same.", "schema": { "type": [ "string", "null" ] } }, { "name": "waiting_on", "in": "query", "description": "Reply state: `us` — the contact answered a message of yours and is waiting on a reply; `customer` — you wrote last and are waiting on them; `none` — nobody (closed or spam, marked \"no reply needed\", or mail you have not answered). New inbound mail does not start as `us`: a conversation waits on you only after a reply of yours, or when you mark it. Spam, automatic replies and mail whose sender could not be verified never do.", "schema": { "type": [ "string", "null" ], "enum": [ "us", "customer", "none", null ] } }, { "name": "sort", "in": "query", "description": "`latest` (default): most recent activity first. `waiting_on_since`: longest-waiting first, threads nobody is waiting on last.", "schema": { "type": [ "string", "null" ], "enum": [ "latest", "waiting_on_since", null ] } }, { "name": "is_spam", "in": "query", "schema": { "type": "string" } }, { "name": "spam_reason", "in": "query", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Archive filtering: default excludes archived, ?archived=1 shows only archived, ?archived=all shows everything", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_read", "in": "query", "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include on top of the always-loaded `contact` and first message: `tags`, `github_links`, `links` (every reference link, GitHub ones included), `summary` (the thread summary: `headline` and `is_stale` only).", "schema": { "type": "string" }, "example": "tags,github_links" }, { "name": "search", "in": "query", "description": "Free-text search over subject, sender address, message bodies (the quote-stripped new content only — quoted history never matches) and the contact's name / email / phone. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched, or null when the hit was on subject / contact. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "`LengthAwarePaginator`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LengthAwarePaginator" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "personalInbox.store", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email", "maxLength": 255 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it the message is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "body": { "type": "string", "description": "Up to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `body` is HTML. It is cleaned before it is saved:\nparagraphs, line breaks, bold, italic, underline, lists, quotes,\ncode and http(s)/mailto links are kept, everything else is removed\n(the text inside unknown tags stays). Left out or false, `body` is\nplain text and any angle brackets in it are shown as typed." }, "workspace_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "attachment_ids": { "type": "array", "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet. Any other id refuses the whole request with a 422 on\n`attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "to", "subject", "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Trial workspaces can only reply to incoming email. Start by sending a message to your workspace address — once a customer emails you, you can reply to that thread. This lifts as soon as your trial converts to a paid plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}": { "get": { "operationId": "personalInbox.show", "description": "`messages` holds the newest 50 messages of the thread, oldest first.\n`messages_limit` picks another number, 0 to 100; 0 leaves them out. A\nlonger thread is not embedded whole: read it a page at a time from\n`GET …/{id}/messages`. `meta.messages` says what was embedded: `total`\nmessages in the thread, how many were `returned`, the `limit` applied,\n`truncated` (true when older messages were left out) and `url`, the\npaged list that holds the whole thread.\n\nEach message row also carries:\n- `text` — plain-text *new content* of the message (HTML flattened, quoted\n history / forwarded chain / signature / legal footer removed). Prefer it\n over the full body for reading, summarising and search.\n- `is_auto_reply` — true for inbound auto-responders (out-of-office,\n mailer-daemon, …) that threaded onto this thread. Such rows do not reopen\n the thread, bump activity or notify agents; skip them when deciding what\n the customer last said.\n- `is_html` — whether the full `body` is HTML: a body that arrived as an\n email's HTML part, or a message posted with `is_html: true`. Everything\n else is plain text.\n\nOpening a conversation marks it read — except with a read-only token,\nwhich leaves `is_read` as it was.", "summary": "Show a personal-inbox conversation with its newest messages", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messages_limit", "in": "query", "description": "How many of the newest messages to embed, 0 to 100. Default 50, also when sent empty. 0 embeds none.", "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 } }, { "name": "with", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "meta": { "type": "object", "properties": { "messages": { "type": "object", "properties": { "total": { "type": "integer" }, "returned": { "type": "integer" }, "limit": { "type": "integer" }, "truncated": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "total", "returned", "limit", "truncated", "url" ] } }, "required": [ "messages" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "personalInbox.update", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] }, "is_read": { "type": "boolean" }, "waiting_on": { "type": [ "string", "null" ], "description": "Override the reply state: `us`, `customer`, or null for \"no reply needed\" (an empty string is refused). The next customer message or reply of yours moves it again. A closed or spam thread has no reply state, so `us` and `customer` are refused there.", "enum": [ "us", "customer", null ] }, "contact_id": { "type": [ "integer", "null" ], "description": "Must be a contact in this workspace. (Scoped the same way\nConversationController::update() scopes it: a bare integer let a\npersonal conversation be repointed at another workspace's\ncontact — #47.)" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "personalInbox.destroy", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/mark-spam": { "post": { "operationId": "personalInbox.spam", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/not-spam": { "post": { "operationId": "personalInbox.notSpam", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The sender is still blocked by a wider rule." }, "data": { "type": "string" }, "still_blocked": { "type": "string" } }, "required": [ "message", "data", "still_blocked" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/archive": { "post": { "operationId": "personalInbox.archive", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/unarchive": { "post": { "operationId": "personalInbox.unarchive", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/restore": { "post": { "operationId": "personalInbox.restore", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/personal-inbox/{id}/force": { "delete": { "operationId": "personalInbox.forceDestroy", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/departed-inboxes": { "get": { "operationId": "departedInbox.index", "description": "One row per member who left this workspace with personal-inbox threads\nbehind them, most recent departure first. `name` and `email` are null\nwhen the member's account has since been deleted. Owners only.", "summary": "List departed members", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "owner_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "resolved_display_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "conversations_count": { "type": "integer" }, "departed_at": { "type": "string" } }, "required": [ "owner_id", "name", "resolved_display_name", "email", "conversations_count", "departed_at" ] } } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can read the inboxes of members who left." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/departed-inboxes/conversations": { "get": { "operationId": "departedInbox.conversations", "description": "The archived personal-inbox threads of members who left, newest activity\nfirst, in the personal-inbox list's row shape plus `owner` (`id`,\n`name`; null once the account is deleted) and `owner_departed_at`.\nOwners only.", "summary": "List a departed member's threads", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "description": "Only the threads of this departed member (the `owner_id` from the departed members list).", "schema": { "type": "integer" }, "example": 42 }, { "name": "search", "in": "query", "description": "Free-text search over subject, sender address, message bodies and the contact's name / email / phone, as on the personal inbox. When set, each result carries `matched_message_id`.", "schema": { "type": "string" }, "example": "invoice" } ], "responses": { "200": { "description": "Paginated set of `Conversation`", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] }, { "type": "null" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can read the inboxes of members who left." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/departed-inboxes/conversations/{id}": { "get": { "operationId": "departedInbox.show", "description": "The thread with its messages (oldest first), contact, tags and GitHub\nlinks, as the personal-inbox thread read returns it, plus `owner` and\n`owner_departed_at`. Reading does not mark it read. The departed\nmember's unsent drafts are not included. Owners only.", "summary": "Read a departed member's thread", "tags": [ "Personal Inbox" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can read the inboxes of members who left." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/plans": { "get": { "operationId": "plan.index", "tags": [ "Plan" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } }, "required": [ "data" ] } } } } } } }, "/v1/workspaces/{workspaceId}/sla-policies": { "get": { "operationId": "slaPolicy.index", "tags": [ "SLA Policies" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SlaPolicy" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "slaPolicy.store", "tags": [ "SLA Policies" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "first_response_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 525600 }, "resolution_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 525600 }, "is_active": { "type": "boolean" } }, "required": [ "priority" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SlaPolicy" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/sla-policies/{id}": { "get": { "operationId": "slaPolicy.show", "tags": [ "SLA Policies" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SlaPolicy" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "slaPolicy.update", "tags": [ "SLA Policies" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "first_response_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 525600 }, "resolution_minutes": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 525600 }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SlaPolicy" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "slaPolicy.destroy", "tags": [ "SLA Policies" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/ses/events": { "post": { "operationId": "sesEvent.handle", "tags": [ "Ses Event" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "ok" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "ignored" } }, "required": [ "status" ] } ] } } } } } } }, "/v1/subscription": { "get": { "operationId": "subscription.show", "tags": [ "Subscription" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "anyOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "null" } ] }, "status": { "type": "string" }, "paddle_status": { "type": "string" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "on_grace_period": { "type": "boolean" }, "on_trial": { "type": "boolean" }, "trial_ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused": { "type": "boolean" } }, "required": [ "plan", "status", "paddle_status", "current_period_end", "on_grace_period", "on_trial", "trial_ends_at", "paused" ] } }, "required": [ "data" ] }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "anyOf": [ { "$ref": "#/components/schemas/Plan" }, { "type": "null" } ] }, "status": { "type": "string", "const": "none" }, "on_grace_period": { "type": "boolean" } }, "required": [ "plan", "status", "on_grace_period" ] } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/subscribe": { "post": { "operationId": "subscription.store", "tags": [ "Subscription" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "integer" }, "return_url": { "type": "string" } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "trial_days": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] } }, "required": [ "data", "trial_days" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/subscription/change": { "post": { "operationId": "subscription.change", "tags": [ "Subscription" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "integer" } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Plan changed successfully." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Subscription canceled. Access continues until the end of the billing period." } }, "required": [ "message" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/subscription/cancel": { "post": { "operationId": "subscription.cancel", "tags": [ "Subscription" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Subscription canceled. Access continues until the end of the billing period." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Subscription is already canceled." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "No active subscription found." } }, "required": [ "message" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/subscription/resume": { "post": { "operationId": "subscription.resume", "tags": [ "Subscription" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Subscription resumed." } }, "required": [ "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No subscription to resume." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tags": { "get": { "operationId": "workspaceTag.index", "tags": [ "Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the tag name.", "schema": { "type": "string" }, "example": "billing" } ], "responses": { "200": { "description": "Paginated set of `Tag`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceTag.store", "tags": [ "Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "color": { "type": "string", "description": "Hex colour, `#RRGGBB`.", "pattern": "^#[0-9A-Fa-f]{6}$", "examples": [ "#3B82F6" ], "minLength": 7, "maxLength": 7 } }, "required": [ "name", "color" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag limit reached for your plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tags/{id}": { "get": { "operationId": "workspaceTag.show", "tags": [ "Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceTag.update", "tags": [ "Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "color": { "type": "string", "description": "Hex colour, `#RRGGBB`.", "pattern": "^#[0-9A-Fa-f]{6}$", "examples": [ "#3B82F6" ], "minLength": 7, "maxLength": 7 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceTag.destroy", "tags": [ "Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/activities": { "get": { "operationId": "ticketActivity.index", "tags": [ "Ticket Activities" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `TicketActivity`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/draft": { "get": { "operationId": "ticketDraft.show", "description": "Returns the unsent draft you have saved on this ticket. When you have\nnone, the answer is still 200, with `data` set to `null`; a ticket you\ncannot see is a 404. This route is your own draft only; the list of every\ndraft on the ticket, your teammates' included, is `GET …/drafts`.\nThe files the draft holds come back in `attachments`.\n\n`meta.last_inbound_at` is when the customer last wrote on this ticket, and\n`meta.is_stale` is true when that was after the draft was last saved — the\ncustomer added something the draft does not answer yet. Any save of the\ndraft clears it, from any client, whether or not that client read the\nnew message first.", "summary": "Get the saved draft reply", "tags": [ "Ticket Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/TicketMessage" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "last_inbound_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_stale": { "type": "boolean", "description": "The cast is for the published schema: Scramble reads `&&` as a string." } }, "required": [ "last_inbound_at", "is_stale" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "null" } }, "required": [ "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "ticketDraft.upsert", "description": "Saves the reply you are still writing, replacing the draft you already had\non this ticket. Reading the draft back returns the same text you sent\n(an `is_html` draft comes back cleaned, as it will be sent).\n\n`to_email`, `cc_emails` and `attachment_ids` are optional: leave a key out\nto keep what the draft already has, or send it as `null` to clear it.", "summary": "Save the draft reply", "tags": [ "Ticket Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The reply you are still writing. It is stored exactly as you send\nit — send only your own new text, never the thread history, which\nis added when the reply is sent rather than when it is drafted.\nUp to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `message` is HTML; it is cleaned exactly as a sent\nreply is. Every save sets the format: a save without it stores\nplain text, even over an HTML draft." }, "from_email": { "type": [ "string", "null" ], "format": "email", "description": "Accepted for compatibility and ignored: a ticket reply is always\nsent from the ticket's own sending address, so a draft does not\nstore one and comes back with `from_email` null.", "maxLength": 255 }, "to_email": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Sending the reply without a `to` uses this\naddress; a `to` on the send wins over it.", "maxLength": 255 }, "cc_emails": { "type": [ "array", "null" ], "description": "Kept with the draft so your composer can show it again. Sending\ndoes not use it: pass the list as `cc` on the reply itself.", "items": { "type": "string", "format": "email", "maxLength": 255 } }, "attachment_ids": { "type": [ "array", "null" ], "description": "Files the draft holds, as ids from the attachment upload endpoint:\nthe complete list each time. An id you leave out is let go and can\nbe used elsewhere. Each file must be in this workspace and not\nalready attached to another message or draft. Sending the reply\nsends these files with it.", "items": { "type": "integer" }, "maxItems": 10 } }, "required": [ "message" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "ticketDraft.destroy", "description": "Deletes your own unsent draft on this ticket. Publishing a draft as a reply\nclears it too, so this is only needed to abandon one. Files the draft held\nare let go, not deleted straight away.", "summary": "Discard the draft reply", "tags": [ "Ticket Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/drafts": { "get": { "operationId": "ticketDrafts.index", "description": "The unsent drafts on this ticket, yours and your teammates', least\nrecently saved first. Each row carries its `author` (`id`, `name`,\n`display_name`, `resolved_display_name`), `is_mine`, the full `body` and\na plain-text `preview`, `is_html`, `to_email`, `cc_emails` and the files\nit holds in `attachments`, which download through the attachment\nendpoint like any other file on the ticket.\n\n`last_inbound_at` is when the customer last wrote. `replied_since` is\ntrue on a teammate's draft when a member has sent a reply on the ticket\nsince it was saved, and `is_stale` is true when either the customer\nwrote again or `replied_since` is.\n\nA teammate's draft is read-only: write your own through `PUT …/draft`.\nA draft whose author is no longer a member of the workspace is not\nlisted.", "summary": "List every draft on the ticket", "tags": [ "Ticket Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "resolved_display_name": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "display_name", "resolved_display_name" ] }, "is_mine": { "type": "boolean" }, "body": { "type": [ "string", "null" ] }, "is_html": { "type": "boolean" }, "preview": { "type": "string" }, "from_email": { "type": [ "string", "null" ] }, "to_email": { "type": [ "string", "null" ] }, "cc_emails": { "type": [ "array", "null" ], "items": { "type": "string" } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "original_filename": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size": { "type": "integer" } }, "required": [ "id", "original_filename", "mime_type", "size" ] } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_inbound_at": { "type": [ "string", "null" ] }, "replied_since": { "type": "boolean" }, "is_stale": { "type": "boolean" } }, "required": [ "id", "author", "is_mine", "body", "is_html", "preview", "from_email", "to_email", "cc_emails", "attachments", "created_at", "updated_at", "last_inbound_at", "replied_since", "is_stale" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/drafts/{draftId}": { "delete": { "operationId": "ticketDrafts.discard", "description": "Deletes one draft on this ticket: your own, or, for a workspace owner, a\nteammate's. Any other member gets a 403 on a draft that is not theirs.\nFiles the draft held are let go, not deleted straight away, and\ndiscarding a teammate's draft adds a `draft_discarded` entry to the\nticket's activity naming whose it was.", "summary": "Discard a draft by id", "tags": [ "Ticket Draft" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No draft found." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only the author or a workspace owner can discard this draft." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{parentId}/github-links": { "get": { "operationId": "ticketGithubLink.index", "tags": [ "Ticket Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GithubLink" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "ticketGithubLink.store", "tags": [ "Ticket Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GithubLink" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{parentId}/github-links/{id}": { "delete": { "operationId": "ticketGithubLink.destroy", "tags": [ "Ticket Github Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{parentId}/links": { "get": { "operationId": "ticketLink.index", "tags": [ "Ticket Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "ticketLink.store", "tags": [ "Ticket Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500 }, "title": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Link" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{parentId}/links/{id}": { "delete": { "operationId": "ticketLink.destroy", "tags": [ "Ticket Link" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/trashed": { "get": { "operationId": "message.trashed", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `TicketMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages": { "get": { "operationId": "message.index", "description": "Messages come back oldest first (`created_at`, then `id`), so walking every\npage returns each message exactly once, in thread order.\n\nEach message row also carries:\n- `text` — plain-text *new content* of the message (HTML flattened, quoted\n history / forwarded chain / signature / legal footer removed). Prefer it\n over the full body for reading, summarising and search.\n- `is_auto_reply` — true for inbound auto-responders (out-of-office,\n mailer-daemon, …) that threaded onto this thread. Such rows do not reopen\n the thread, bump activity or notify agents; skip them when deciding what\n the customer last said.\n- `is_html` — whether the full `message` body is HTML: a body that arrived\n as an email's HTML part, or a reply or note posted with `is_html: true`.\n Everything else is plain text.\n- `images_trusted` — true when the From address is one of the workspace's\n trusted senders (`GET …/trusted-senders`), so a client may load the\n message's external images without asking. Never true for mail that\n failed DMARC or was accepted without proof of its From.", "summary": "List ticket messages", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `TicketMessage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "message.store", "description": "Posts either an agent reply (`type: email`, delivered to the contact) or an\ninternal note. A reply does not need the caller to paste the thread history\ninto the body: the message to be quoted is recorded when the reply is created\n(returned as `quote_source_message_id`) and the quote itself is rendered while\nthe email is being built, so the stored message is only what the agent wrote.\n\nTo send only the files you list, whatever your saved draft holds, pass\n`attachments_exact: true` with `attachment_ids`.\n\nIf you have a saved draft on this ticket, an email reply replaces it and is\nstamped with the time you send it. Without a `to`, the reply goes to the\ndraft's `to_email` when it has one; a `to` sent as null or an empty string\nignores it and uses the thread's own reply address. Files attached to your draft go out with the\nreply; `attachment_ids` may name them again or add more, up to 10 in all. An\ninternal note leaves your draft alone.", "summary": "Create a ticket message", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_id": { "type": "integer", "description": "Optional, and best omitted: a message is always attributed to the\nauthenticated user. If you do send it, it must be your own user id\n— any other id is rejected with 422 rather than silently\nre-attributed, so an importer that expects per-agent attribution\nfinds out instead of getting every reply signed as the token owner. Expressed as a closure rather than Rule::in([auth()->id()]) so the\ngenerated OpenAPI spec does not publish an `enum` built from the\nid of whoever (nobody) is authenticated at doc-generation time." }, "message": { "type": "string", "description": "What you are saying now, and only that: the thread history is\nattached to the outgoing email for you, so a body that repeats it\nreaches the contact with the conversation quoted twice. Up to\n10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `message` is HTML. It is cleaned before it is saved:\nparagraphs, line breaks, bold, italic, underline, lists, quotes,\ncode and http(s)/mailto links are kept, everything else is removed\n(the text inside unknown tags stays). Links are kept as plain text\nwhile the workspace is on a trial. Left out or false, `message` is\nplain text and any angle brackets in it are shown as typed." }, "attachments_exact": { "type": "boolean", "description": "Send true to make `attachment_ids` the complete list of files on this reply. Any file your saved draft holds that is not listed is taken off the draft before it is sent; it becomes an unused upload again and is removed a day later. With `attachment_ids` left out, null or empty, the reply then carries no files. Left out or false, every file on your draft goes out, plus the ones listed. Has no effect on an internal note, which never uses the draft." }, "type": { "type": "string", "enum": [ "email", "internal_note" ] }, "include_quote": { "type": "boolean", "description": "Controls whether the outgoing email carries the thread history. Left\nat its default of true, the preceding message is attached as a quote\n(a collapsible blockquote in the HTML part, `> ` prefixed lines in the\nplain-text one). Pass false for an unquoted reply. Notes ignore it." }, "to": { "type": [ "string", "null" ], "format": "email", "description": "Who the reply goes to. Left out, it is the recipient saved on your\ndraft, else the latest customer message's Reply-To, else the\ncontact. A `to` you pass always wins over the draft's; pass it as\nnull or an empty string to ignore the draft's and reply where the\nthread already goes. On a trial\nworkspace a drafted address that is not already on the thread is\nrefused with 403, exactly like one passed here.", "maxLength": 255 }, "cc": { "type": "array", "description": "The CC list of this reply, and the only one used: CC addresses\nsaved on your draft are not carried over, so pass them here again.", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Send even when `to` or a `cc` address belongs to a contact whose status is not `active`. Without it such a reply is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "attachment_ids": { "type": [ "array", "null" ], "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet, or are on your saved draft. Any other id refuses the\nwhole request with a 422 on `attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 }, "mentioned_user_ids": { "type": "array", "description": "Members to notify about an internal note, at most 50.", "items": { "type": "integer", "description": "Every id must belong to a member of this workspace, once; any\nother id is rejected. (The array is stored on the note verbatim\nand echoed back, so a foreign id must never reach the row — not\nmerely be skipped when the notifications go out.)" }, "maxItems": 50, "uniqueItems": true } }, "required": [ "message", "type" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}/resend": { "post": { "operationId": "message.resend", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Resend even when the recipient or a cc address belongs to a contact whose status is not `active`. Without it that is refused with 422 (`code: contact_not_sendable`)." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Email queued for resend" } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "outbound_limit_reached" }, "message": { "type": "string" }, "retry_after": { "type": "string" }, "usage": { "type": "string" } }, "required": [ "error", "message", "retry_after", "usage" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}/reparse": { "post": { "operationId": "message.reparse", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ] }, { "type": "string" } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}/restore": { "post": { "operationId": "message.restore", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}/raw": { "get": { "operationId": "message.rawPayload", "description": "Returns the stored raw email (RFC 822 / MIME source) of an inbound\nmessage as `text/plain`. Pass `download=1` to receive it as a\n`message/rfc822` attachment named `.eml` instead.\n\n404 when the message did not arrive by email or its stored source is\nno longer available.", "summary": "View the original email", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "description": "Set to `1` to receive the source as a `message/rfc822` attachment download named `.eml` instead of inline text.", "schema": { "type": "boolean" }, "example": 1 } ], "responses": { "200": { "description": "The stored raw email source.", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "message/rfc822": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "schema": { "type": "string", "enum": [ "chunked" ] } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "Content-Disposition": { "schema": { "type": "string" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file is empty" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Raw payload file not found on disk" } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "No raw payload available for this message" } }, "required": [ "message" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}/force": { "delete": { "operationId": "message.forceDestroy", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticket_id}/messages/{message_id}": { "delete": { "operationId": "message.destroy", "tags": [ "Ticket Messages" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The first message of a ticket cannot be deleted." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{parentId}/summary": { "get": { "operationId": "ticketSummary.show", "description": "Besides the stored columns, the response carries `is_stale` and `messages_since`\n(messages the summary does not cover), `body_html` (the Markdown rendered: raw\nHTML escaped, images left out, links opening in a new tab) and\n`updated_by {id, name}`. Works on a trashed thread too.", "summary": "Get the thread's summary", "tags": [ "Ticket Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "ticketSummary.upsert", "description": "Plain Markdown, at most 1,000 characters, no HTML tags or entities. The\nheadline is derived from the first line. `covers_message_id` moves to the\nthread's newest message, so a fresh write is never stale. `replaced` says\nwhether an earlier summary was overwritten. A trashed thread answers 404.", "summary": "Write the thread's summary (create or replace)", "tags": [ "Ticket Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 1000 } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Three attempts, as the draft upserts do: a deadlock between two writers is retried.", "$ref": "#/components/schemas/ThreadSummary" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "ticketSummary.destroy", "summary": "Remove the thread's summary. A trashed thread answers 404", "tags": [ "Ticket Summary" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No summary." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/tags": { "get": { "operationId": "ticketTag.index", "tags": [ "Ticket Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "ticketTag.store", "description": "`data` is the tag. A new tag can start `ticket_tag_added` automation rules, which run\nbefore this responds; `meta.thread` says what the ticket looks like after them:\n`trashed` and `is_spam`, and `automations`, the rules this add set off in run order\n(`id`, `name`, and the action types each applied, e.g. `move_to_trash`,\n`mark_as_spam`, `add_tag`, `assign_agent`). `trashed` is also true for a ticket\nthat was in the trash before; `automations` is then empty.", "summary": "Add a tag to the ticket, by `tag_id` or by `tag_name` (created when missing)", "tags": [ "Ticket Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_id": { "type": "integer" }, "tag_name": { "type": "string", "minLength": 1, "maxLength": 255 } } } } } }, "responses": { "201": { "description": "The tag, and the ticket after any tag-added rules (`meta.thread`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "meta": { "type": "object", "properties": { "thread": { "type": "object", "properties": { "trashed": { "type": "boolean" }, "is_spam": { "type": "boolean" }, "automations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "actions" ] } } }, "required": [ "trashed", "is_spam", "automations" ] } }, "required": [ "thread" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag limit reached for your plan." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{ticketId}/tags/{tagId}": { "delete": { "operationId": "ticketTag.destroy", "tags": [ "Ticket Tags" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Tag is not attached to this ticket." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/trashed": { "get": { "operationId": "workspaceTicket.trashed", "description": "Each ticket carries `preview`, as on the ticket list: its first message as\nplain text, cut to at most 255 characters.", "summary": "List trashed tickets", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contact`, `agent`, `github_links`, `links`.", "schema": { "type": "string" }, "example": "contact,agent" }, { "name": "search", "in": "query", "description": "Free-text search over subject, description, sender address, message bodies (the quote-stripped new content only — quoted history never matches) and the contact's name / email / phone. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched (a description hit resolves to the first message), or null when the hit was on subject / contact. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "Paginated set of `Ticket`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/bulk": { "post": { "operationId": "workspaceTicket.bulkAction", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 100 }, "action": { "type": "string", "enum": [ "trash", "spam", "not_spam", "restore", "force_delete", "assign", "unassign", "close", "reopen", "archive", "unarchive", "mark_read", "mark_unread", "add_tag", "remove_tag" ] }, "agent_id": { "type": [ "integer", "null" ] }, "tag_id": { "type": [ "integer", "null" ] } }, "required": [ "ids", "action" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "affected": { "type": "integer", "minimum": 0 }, "still_blocked": { "type": "string" } }, "required": [ "affected", "still_blocked" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/spam": { "delete": { "operationId": "workspaceTicket.deleteAllSpam", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets": { "get": { "operationId": "workspaceTicket.index", "description": "Each ticket carries `preview`: its first message as plain text, with tags\nremoved, HTML entities decoded and whitespace collapsed, cut to at most\n255 characters. An empty first message gives an empty string.\n`description` still holds the first message's full HTML.", "summary": "List tickets", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "tag", "in": "query", "description": "Only tickets carrying the tag with this name. The whole name must match; upper and lower case are treated the same.", "schema": { "type": [ "string", "null" ] } }, { "name": "waiting_on", "in": "query", "description": "Reply state: `us` — the customer wrote last and is waiting on a reply; `customer` — you replied and are waiting on them; `none` — nobody (closed or spam, marked \"no reply needed\", or no message that counts yet). Mail flagged as spam, automatic replies and mail whose sender could not be verified never put a ticket on `us`.", "schema": { "type": [ "string", "null" ], "enum": [ "us", "customer", "none", null ] } }, { "name": "sort", "in": "query", "description": "`latest` (default): most recent activity first. `waiting_on_since`: longest-waiting first, threads nobody is waiting on last.", "schema": { "type": [ "string", "null" ], "enum": [ "latest", "waiting_on_since", null ] } }, { "name": "external_reference", "in": "query", "description": "Only the ticket created with this `external_reference` — how an integration finds the ticket it opened for one of its own records. The whole reference must match, no wildcards; upper and lower case, and accents, are treated the same. Like every filter here it leaves out archived and spam tickets unless `archived=all` / `is_spam=all` is passed, and it never lists a trashed ticket (a create with that reference still returns it).", "schema": { "type": [ "string", "null" ], "maxLength": 191 } }, { "name": "is_spam", "in": "query", "description": "Spam filtering: default excludes spam, ?is_spam=1 shows only spam, ?is_spam=all shows everything", "schema": { "type": "string" } }, { "name": "spam_reason", "in": "query", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "description": "Archive filtering: default excludes archived, ?archived=1 shows only archived, ?archived=all shows everything", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_read", "in": "query", "schema": { "type": "string" } }, { "name": "sla_status", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contact`, `agent`, `tags`, `sla`, `github_links`, `links` (every reference link, GitHub ones included), `summary` (the thread summary: `headline` and `is_stale` only).", "schema": { "type": "string" }, "example": "contact,agent,tags" }, { "name": "search", "in": "query", "description": "Free-text search over subject, description, sender address, message bodies (the quote-stripped new content only — quoted history never matches), the contact's name / email / phone, and an exact `external_reference`. When set, each result carries `matched_message_id`: the oldest message whose sender address or body matched (a description hit resolves to the first message), or null when the hit was on subject / contact / reference. A message consisting only of quoted or forwarded material is searchable as a whole.", "schema": { "type": "string" }, "example": "INV-4711" } ], "responses": { "200": { "description": "Paginated set of `Ticket`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceTicket.store", "description": "Set `external_reference` to make the create safe to repeat: when a\nticket in this workspace already carries that reference, it is returned\nwith 200 (`meta.replayed: true`, `meta.matched_by: external_reference`,\nheader `Idempotent-Replayed: true`) instead of a second ticket, and\nnobody is emailed — however long ago it was created, and even when it\nis in the trash (`deleted_at` set).", "summary": "Create a ticket", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": [ "integer", "null" ], "description": "Existing contact in this workspace" }, "contact": { "type": "object", "description": "Inline contact, found-or-created by email", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "organization_id": { "type": [ "integer", "null" ] } } }, "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "description": "Up to 10,000 characters of plain text, or 40,000 with `is_html`.", "minLength": 1, "maxLength": 10000 }, "is_html": { "type": "boolean", "description": "Send true when `description` is HTML. It is cleaned before it is\nsaved: paragraphs, line breaks, bold, italic, underline, lists,\nquotes, code and http(s)/mailto links are kept, everything else is\nremoved (the text inside unknown tags stays). Left out or false,\n`description` is plain text and any angle brackets in it are shown\nas typed." }, "status": { "type": "string", "enum": [ "open", "in_progress", "closed", "pending" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "agent_id": { "type": [ "integer", "null" ] }, "workspace_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 255 }, "maxItems": 25 }, "force": { "type": "boolean", "description": "Create the ticket even when the contact, or a `cc` address, belongs to a contact whose status is not `active` and the workspace would email them a confirmation. Without it that is refused with 422: `code` is `contact_not_sendable` and `contacts` lists who was refused and why." }, "attachment_ids": { "type": "array", "description": "Ids returned by POST /attachments in this workspace that are not on\na message yet. Any other id refuses the whole request with a 422 on\n`attachment_ids`, and nothing is saved.", "items": { "type": "integer" }, "maxItems": 10 }, "external_reference": { "type": [ "string", "null" ], "description": "Your own id for this ticket, unique in this workspace — e.g. another system's conversation id plus an episode number, or an order id. A create whose reference already names a ticket returns that ticket with 200 and creates and emails nothing. One line of text, trimmed; empty means none; upper and lower case, and accents, are treated the same (`Order-É1` and `order-e1` are one reference). Filter the ticket list on it with `?external_reference=`.", "maxLength": 191 } }, "required": [ "subject", "description", "priority" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Ticket" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "replayed": { "type": "boolean" }, "matched_by": { "type": "string", "const": "external_reference" } }, "required": [ "replayed", "matched_by" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "const": "Contact does not belong to current workspace." } }, "required": [ "message" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Contact not found." } }, "required": [ "message" ] } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Trial workspaces can only reply to incoming email. Start by sending a message to your workspace address — once a customer emails you, you can reply to that thread. This lifts as soon as your trial converts to a paid plan." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}": { "get": { "operationId": "workspaceTicket.show", "description": "Opening a ticket marks it read — except with a read-only token, which\nleaves `is_read` as it was, so an integration reading tickets does not\nclear the team's unread markers.", "summary": "Show a ticket", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contact`, `agent`, `tags`, `sla`, `github_links`, `links` (every reference link, GitHub ones included), `summary` (the thread summary with `is_stale`, `messages_since` and `body_html`), `drafts` (every unsent draft on the ticket, your teammates' included; the rows of `GET …/tickets/{id}/drafts`).", "schema": { "type": "string" }, "example": "contact,agent,tags" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceTicket.update", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "description": "Fixed once the ticket exists: it is the text the ticket was opened\nwith, kept as the first message of the thread. Add a note or a\nreply instead." }, "status": { "type": "string", "enum": [ "open", "in_progress", "closed", "pending" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "agent_id": { "type": [ "integer", "null" ] }, "is_read": { "type": "boolean" }, "waiting_on": { "type": [ "string", "null" ], "description": "Override the reply state: `us`, `customer`, or null for \"no reply needed\" (an empty string is refused). The next customer message or reply of yours moves it again. A closed or spam thread has no reply state, so `us` and `customer` are refused there.", "enum": [ "us", "customer", null ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceTicket.destroy", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/resend-confirmation": { "post": { "operationId": "workspaceTicket.resendConfirmationEmail", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Send it even when the ticket's contact has a status other than `active`. Without it that is refused with 422 (`code: contact_not_sendable`)." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Confirmation email queued." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ContactNotSendableException" }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Ticket has no contact." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/mark-spam": { "post": { "operationId": "workspaceTicket.markSpam", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/not-spam": { "post": { "operationId": "workspaceTicket.notSpam", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The sender is still blocked by a wider rule." }, "data": { "$ref": "#/components/schemas/Ticket" }, "still_blocked": { "type": "string" } }, "required": [ "message", "data", "still_blocked" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/archive": { "post": { "operationId": "workspaceTicket.archive", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/unarchive": { "post": { "operationId": "workspaceTicket.unarchive", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/answered-externally": { "post": { "operationId": "workspaceTicket.answeredExternally", "description": "Records that a member already answered the customer outside PimiDesk — from their own\nmailbox without copying the ticket address, by phone, on chat. The ticket moves the way a\nreply does: it waits on the customer, its first response is met if it was not yet, and its\nactivity time moves. An `answered_externally` activity row keeps the note. Nothing is sent,\nand status, read state and archive state are left as they are. Repeating the latest mark with\nthe same note changes nothing. A closed or spam ticket has no reply state and is refused with\n422: reopen it, or mark it not spam, first.", "summary": "Mark a ticket answered externally", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "description": "Where and when the answer went, kept on the activity row (\"Replied from Gmail on 22 Sep\"). Optional.", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Ticket" }, { "type": "null" } ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/restore": { "post": { "operationId": "workspaceTicket.restore", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/tickets/{id}/force": { "delete": { "operationId": "workspaceTicket.forceDestroy", "tags": [ "Tickets" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/trusted-senders": { "get": { "operationId": "trustedSender.index", "description": "Newest first, with the member who added each one (`created_by_user`).", "summary": "List trusted senders", "tags": [ "Trusted Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Substring match on the trusted address or domain; a leading `@` is ignored.", "schema": { "type": "string" }, "example": "paddle.com" } ], "responses": { "200": { "description": "Paginated set of `TrustedSender`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "trustedSender.store", "description": "Idempotent: a value that is already trusted (after normalizing: lowercase,\nno leading `@` on a domain) returns the existing row. A domain matches\nexactly; subdomains are not included. Patterns and free-mail domains such\nas gmail.com are refused; an address at one may be trusted.", "summary": "Trust a sender", "tags": [ "Trusted Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "An address (`billing@paddle.com`) or a domain (`paddle.com` or `@paddle.com`).", "examples": [ "billing@paddle.com" ], "maxLength": 255 }, "match_type": { "type": [ "string", "null" ], "description": "`exact` for one address or `domain` for every address at that domain. Omit to detect it from the value.", "enum": [ "exact", "domain", null ], "examples": [ "exact" ] } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrustedSender" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/trusted-senders/{id}": { "delete": { "operationId": "trustedSender.destroy", "description": "Their images are hidden again from the next read of a thread.", "summary": "Stop trusting a sender", "tags": [ "Trusted Senders" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/version": { "get": { "operationId": "version", "description": "Reports the version of the PimiDesk API currently serving your requests.\nPublic: no authentication required. This is the only endpoint outside the\n`/v1` prefix, so it stays reachable across future API versions.", "summary": "Get the API version", "tags": [ "Version" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" } }, "required": [ "version" ] } } } } } } }, "/v1/workspaces/{workspace_id}/webhooks/events": { "get": { "operationId": "webhook.events", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/webhooks": { "get": { "operationId": "webhook.index", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the endpoint URL and description.", "schema": { "type": "string" }, "example": "hooks.example.com" } ], "responses": { "200": { "description": "Paginated set of `Webhook`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "webhook.store", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "ticket.created", "ticket.updated", "ticket.closed", "ticket.reopened", "ticket.assigned", "ticket.replied", "ticket.tagged", "ticket.deleted", "conversation.created", "conversation.replied", "conversation.closed", "conversation.assigned", "conversation.tagged", "contact.created", "contact.updated", "contact.deleted", "sla.breached" ] }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "is_active": { "type": "boolean" } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": {} }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string" } }, "required": [ "id", "workspace_id", "url", "events", "description", "is_active", "created_at", "updated_at", "secret" ] } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Webhook limit reached for your plan." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage webhooks." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/webhooks/{id}": { "get": { "operationId": "webhook.show", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": {} }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "masked_secret": { "type": "string" } }, "required": [ "id", "workspace_id", "url", "events", "description", "is_active", "created_at", "updated_at", "masked_secret" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "webhook.update", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "ticket.created", "ticket.updated", "ticket.closed", "ticket.reopened", "ticket.assigned", "ticket.replied", "ticket.tagged", "ticket.deleted", "conversation.created", "conversation.replied", "conversation.closed", "conversation.assigned", "conversation.tagged", "contact.created", "contact.updated", "contact.deleted", "sla.breached" ] }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": {} }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "masked_secret": { "type": "string" } }, "required": [ "id", "workspace_id", "url", "events", "description", "is_active", "created_at", "updated_at", "masked_secret" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage webhooks." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "webhook.destroy", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage webhooks." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/webhooks/{id}/regenerate-secret": { "post": { "operationId": "webhook.regenerateSecret", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage webhooks." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/webhooks/{id}/test": { "post": { "operationId": "webhook.test", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Test webhook queued for delivery." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage webhooks." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/webhooks/{id}/deliveries": { "get": { "operationId": "webhook.deliveries", "tags": [ "Webhooks" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `WebhookDelivery`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-lists": { "get": { "operationId": "workspaceContactList.index", "tags": [ "Workspace Contact List" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated extras to include: `contacts_count`.", "schema": { "type": "string" }, "example": "contacts_count" }, { "name": "search", "in": "query", "description": "Free-text search over the list name.", "schema": { "type": "string" }, "example": "Newsletter" } ], "responses": { "200": { "description": "Paginated set of `ContactList`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceContactList.store", "tags": [ "Workspace Contact List" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactList" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/contact-lists/{id}": { "get": { "operationId": "workspaceContactList.show", "tags": [ "Workspace Contact List" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "with", "in": "query", "description": "Comma-separated relations to include: `contacts`.", "schema": { "type": "string" }, "example": "contacts" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactList" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceContactList.update", "tags": [ "Workspace Contact List" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactList" } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceContactList.destroy", "tags": [ "Workspace Contact List" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/emails/available-domains": { "get": { "operationId": "workspaceEmail.availableDomains", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "domain": { "type": "string" }, "send_verified": { "type": "boolean" }, "mx_verified": { "type": "boolean" } }, "required": [ "id", "domain", "send_verified", "mx_verified" ] } } }, "required": [ "data" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/emails": { "get": { "operationId": "workspaceEmail.index", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purpose", "in": "query", "description": "`ticket` or `inbox`; comma-separate the two to list both.", "schema": { "type": [ "string", "null" ] } }, { "name": "can_send", "in": "query", "schema": { "type": "string" } }, { "name": "mine", "in": "query", "description": "Only the current user's personal-inbox addresses (`user_id` = you).", "schema": { "type": "boolean" }, "example": true }, { "name": "shared", "in": "query", "description": "Only shared addresses (no `user_id`). Ignored when `mine` is set.", "schema": { "type": "boolean" }, "example": true }, { "name": "search", "in": "query", "description": "Free-text search over the address.", "schema": { "type": "string" }, "example": "support@example.com" } ], "responses": { "200": { "description": "Paginated set of `WorkspaceEmail`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceEmail.store", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "purpose": { "type": "string", "enum": [ "ticket", "inbox" ] }, "user_id": { "type": [ "integer", "null" ], "description": "The member whose personal inbox this is. Only for purpose\n`inbox` — omitted, purpose is `ticket`, so send both together." }, "sender_name": { "type": [ "string", "null" ], "maxLength": 255 }, "receive_method": { "type": [ "string", "null" ], "enum": [ "forwarding", "mx", null ] }, "can_send": { "type": "boolean" }, "code": { "type": "string", "minLength": 6, "maxLength": 6 } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceEmail" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "type": "null" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Email limit reached for your plan." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage emails." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/emails/send-verification": { "post": { "operationId": "workspaceEmail.sendVerification", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string", "const": "Verification code sent." } }, "required": [ "message" ] } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "retry_after": { "type": "integer" } }, "required": [ "message", "retry_after" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "Email limit reached for your plan." } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage emails." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/emails/custom": { "post": { "operationId": "workspaceEmail.storeCustom", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "code": { "type": "string", "minLength": 6, "maxLength": 6 }, "purpose": { "type": "string", "enum": [ "ticket", "inbox" ] }, "sender_name": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "email", "code" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceEmail" } }, "required": [ "data" ] } } } }, "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceEmail" } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Email limit reached for your plan." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage emails." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/emails/{id}": { "get": { "operationId": "workspaceEmail.show", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceEmail" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceEmail.update", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "ticket", "inbox" ] }, "user_id": { "type": [ "integer", "null" ], "description": "The member whose personal inbox this is. Only for purpose\n`inbox`: the address's own, or one sent in the same request." }, "sender_name": { "type": [ "string", "null" ], "maxLength": 255 }, "can_send": { "type": "boolean" }, "receive_method": { "type": [ "string", "null" ], "enum": [ "forwarding", "mx", null ] }, "code": { "type": "string", "minLength": 6, "maxLength": 6 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceEmail" } }, "required": [ "data" ] }, { "type": "null" } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage emails." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceEmail.destroy", "tags": [ "Workspace Emails" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Platform email cannot be deleted." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only workspace owners can manage emails." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/invitations": { "get": { "operationId": "workspaceInvitation.index", "tags": [ "Workspace Invitation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `WorkspaceInvitation`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "string" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "string" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspaceInvitation.store", "tags": [ "Workspace Invitation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "type": "string", "enum": [ "owner", "member" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceInvitation" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "retry_after": { "type": "string" } }, "required": [ "message", "retry_after" ] }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/invitations/{id}/resend": { "post": { "operationId": "workspaceInvitation.resend", "tags": [ "Workspace Invitation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceInvitation" } }, "required": [ "data" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "retry_after": { "type": "string" } }, "required": [ "message", "retry_after" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/invitations/{id}": { "delete": { "operationId": "workspaceInvitation.destroy", "tags": [ "Workspace Invitation" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/users": { "get": { "operationId": "workspaceUser.index", "description": "Each member carries `is_creator`: true for the workspace's creator, the\nowner of record whose plan the workspace runs on (see\n`POST /workspaces/{id}/transfer-creator`). A workspace made by a\nplatform admin may have no creator, and then every member reads false.", "summary": "List workspace members", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Free-text search over the member's name, display name and email.", "schema": { "type": "string" }, "example": "alice" } ], "responses": { "200": { "description": "Paginated set of `User`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/users/{id}": { "get": { "operationId": "workspaceUser.show", "description": "Carries `is_creator`, as the list does.", "summary": "Show a workspace member", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspaceUser.update", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role_in_workspace": { "type": "string", "enum": [ "owner", "member" ] }, "name": { "type": "string", "description": "Not accepted. A member's name belongs to their account and is changed by that user via `PUT /account`. Sending it is rejected with 422." }, "email": { "type": "string", "description": "Not accepted. A member's email belongs to their account and is changed by that user via `PUT /account`. Sending it is rejected with 422." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "last_owner" } }, "required": [ "message", "code" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "The workspace creator cannot be demoted or removed. Transfer ownership first." }, "code": { "type": "string", "const": "creator_locked" } }, "required": [ "message", "code" ] } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspaceUser.destroy", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "const": "last_owner" } }, "required": [ "message", "code" ] }, { "type": "object", "properties": { "message": { "type": "string", "const": "The workspace creator cannot be demoted or removed. Transfer ownership first." }, "code": { "type": "string", "const": "creator_locked" } }, "required": [ "message", "code" ] } ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "You cannot remove yourself from the workspace." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{workspaceId}/hidden-channels": { "get": { "operationId": "hiddenChannel.index", "description": "The channels you have hidden from your own sidebar in this workspace:\nany of `tickets`, `shared_inbox`, `personal_inbox`. Empty when nothing\nis hidden. A display preference only — a hidden channel stays reachable\nand its notifications are unchanged.", "summary": "Show your hidden channels", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hidden_channels": { "type": "array", "items": { "type": "string" } } }, "required": [ "hidden_channels" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "hiddenChannel.update", "description": "Replaces the list. It applies to you alone, in this workspace alone;\nan empty list shows every channel again.", "summary": "Set your hidden channels", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hidden_channels": { "type": "array", "description": "The complete list of channels to hide: any of `tickets`, `shared_inbox`, `personal_inbox`. Send an empty list to show them all.", "items": { "type": "string", "enum": [ "tickets", "shared_inbox", "personal_inbox" ] }, "maxItems": 3 } }, "required": [ "hidden_channels" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hidden_channels": { "type": "array", "items": { "type": "string" } } }, "required": [ "hidden_channels" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces": { "get": { "operationId": "workspace.index", "description": "The workspaces you belong to. Each one carries `hidden_channels`: the\nchannels (`tickets`, `shared_inbox`, `personal_inbox`) you have hidden\nfrom your own sidebar there. It is your own list, never another member's.", "summary": "List workspaces", "tags": [ "Workspaces" ], "responses": { "200": { "description": "`LengthAwarePaginator`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LengthAwarePaginator" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "workspace.store", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "429": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Workspace limit reached for your plan." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{id}": { "get": { "operationId": "workspace.show", "description": "The workspace carries `hidden_channels`: the channels (`tickets`,\n`shared_inbox`, `personal_inbox`) you have hidden from your own sidebar\nin it. It is your own list, never another member's.", "summary": "Show a workspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "workspace.update", "description": "Owners only. The returned workspace carries `hidden_channels`, your own\nhidden sidebar channels; change those with `PUT …/hidden-channels`.", "summary": "Update a workspace", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "tickets_enabled": { "type": "boolean" }, "shared_inbox_enabled": { "type": "boolean" }, "personal_inbox_enabled": { "type": "boolean" }, "send_confirmation_email": { "type": "boolean", "description": "Behaviour flag, not a feature — kept out of the invariant below." } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "workspace.destroy", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{id}/usage": { "get": { "operationId": "workspace.usage", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{id}/dashboard": { "get": { "operationId": "workspace.dashboard", "summary": "The dashboard home: the caller's queue, team workload and recent activity.\nThe counts and lists are built by WorkspaceOverview, which the MCP\nworkspace_overview tool reads too, so the two cannot drift", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "my_open_tickets": { "type": "integer" }, "unassigned_tickets": { "type": "integer" }, "unread_tickets": { "type": "integer" }, "my_open_conversations": { "type": "integer" }, "unassigned_conversations": { "type": "integer" }, "unread_conversations": { "type": "integer" }, "open_personal_conversations": { "type": "integer" }, "unread_personal_conversations": { "type": "integer" }, "sla_breached": { "type": "integer" }, "recent_my_tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "recent_activity": { "type": "array", "items": { "$ref": "#/components/schemas/TicketActivity" } }, "recent_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "recent_personal_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "agent_workload": { "type": "string" }, "onboarding": { "type": "object", "properties": { "has_custom_email": { "type": "boolean" }, "member_count": { "type": "integer" } }, "required": [ "has_custom_email", "member_count" ] } }, "required": [ "my_open_tickets", "unassigned_tickets", "unread_tickets", "my_open_conversations", "unassigned_conversations", "unread_conversations", "open_personal_conversations", "unread_personal_conversations", "sla_breached", "recent_my_tickets", "recent_activity", "recent_conversations", "recent_personal_conversations", "agent_workload", "onboarding" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{id}/status": { "get": { "operationId": "workspace.status", "description": "The whole workspace snapshot in one call: current plan usage, ticket counts\nby status, and shared and personal inbox counts. The counts apply the same\ndefaults as the matching list endpoints — spam, archived and deleted records\nare excluded, the shared inbox covers conversations nobody owns, and the\npersonal inbox covers only the conversations owned by the authenticated user.\nA feature turned off for the workspace reports `enabled: false` and no counts.\n\nThe `usage` object is identical to the one `GET /workspaces/{id}/usage`\nreturns, where a `null` limit means unlimited.", "summary": "Aggregate workspace status", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "usage": { "type": "object", "additionalProperties": {} }, "tickets": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "open": { "type": "integer" }, "in_progress": { "type": "integer" }, "pending": { "type": "integer" }, "active": { "type": "integer" } }, "required": [ "enabled" ] }, "shared_inbox": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "open": { "type": "integer" }, "unread": { "type": "integer" } }, "required": [ "enabled" ] }, "personal_inbox": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "unread": { "type": "integer" } }, "required": [ "enabled" ] } }, "required": [ "usage", "tickets", "shared_inbox", "personal_inbox" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/workspaces/{id}/transfer-creator": { "post": { "operationId": "workspace.transferCreator", "description": "The creator is the workspace's owner of record: the workspace runs on\nthe creator's plan and subscription (a trial makes it reply-only), the\ncreator's account counts it toward their workspace limit, and the\ncreator gets the owner emails such as domain and sending alerts. Only\nthe current creator can hand the role to another member, who must\nalready be an owner of the workspace. Nobody's role changes: the\nprevious creator stays an owner. Both people are emailed.\n\nThe transfer is refused with 422 and a `code` saying why when the new\ncreator is not an owner (`target_not_owner`), is already the creator\n(`target_is_creator`), is suspended (`target_banned`), has not verified\ntheir email (`target_unverified`), has no active subscription\n(`target_not_entitled`), is on a trial (`target_on_trial`), or has\nreached their plan's workspace limit (`target_workspace_limit`). A\ncaller who is not the creator gets 403 (`not_creator`). Returns the\nworkspace with its new `created_by`.", "summary": "Transfer the creator role", "tags": [ "Workspaces" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The member to make the creator. Must already be an owner of this workspace." } }, "required": [ "user_id" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] }, { "type": "string" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Only the workspace creator can transfer the creator role." }, "code": { "type": "string", "const": "not_creator" } }, "required": [ "message", "code" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "Automation": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "event": { "type": "string" }, "match": { "$ref": "#/components/schemas/AutomationMatch" }, "conditions": { "type": "array", "items": {} }, "actions": { "type": "array", "items": {} }, "priority": { "type": "integer" }, "stop_on_match": { "type": "boolean" }, "is_active": { "type": "boolean" }, "last_matched_at": { "type": [ "string", "null" ], "format": "date-time" }, "match_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "name", "event", "match", "conditions", "actions", "priority", "stop_on_match", "is_active", "last_matched_at", "match_count", "created_at", "updated_at" ], "title": "Automation" }, "AutomationMatch": { "type": "string", "description": "How an automation combines its conditions. `All` is the original AND: every condition must pass. `Any` is OR: the rule fires as soon as one condition passes, so one rule can cover several subject patterns instead of a clone per pattern.\n", "enum": [ "all", "any" ], "title": "AutomationMatch" }, "BlockMatchType": { "type": "string", "description": "How a blocked_senders row matches an inbound sender. `exact` is the pre-#108 behaviour and the default, so a client that still posts `{email}` alone gets what it always got.\n", "enum": [ "exact", "domain", "pattern" ], "title": "BlockMatchType" }, "BlockSource": { "type": "string", "description": "Who applied a block: `manual` (added on purpose), `spam_action` (marking a thread as spam) or `auto` (the rate-based auto-ban). Marking a thread as not spam lifts only a `spam_action` block.\n", "enum": [ "manual", "auto", "spam_action" ], "title": "BlockSource" }, "BlockedSender": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "email": { "type": "string" }, "match_type": { "$ref": "#/components/schemas/BlockMatchType" }, "source": { "$ref": "#/components/schemas/BlockSource" }, "reason": { "type": [ "string", "null" ] }, "applied_by": { "type": [ "integer", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "hit_count": { "type": "integer" }, "last_hit_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "string" } }, "required": [ "id", "workspace_id", "email", "match_type", "source", "reason", "applied_by", "expires_at", "hit_count", "last_hit_at", "created_at", "updated_at", "is_active" ], "title": "BlockedSender" }, "CannedResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "content": { "type": "string" }, "workspace_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "content", "workspace_id", "created_at", "updated_at" ], "title": "CannedResponse" }, "Checkout": { "type": "string", "title": "Checkout" }, "Contact": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "organization_id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ContactStatus" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "gravatar_url": { "type": "string" } }, "required": [ "id", "workspace_id", "organization_id", "name", "title", "email", "phone", "notes", "external_id", "timezone", "status", "status_reason", "status_changed_at", "created_at", "updated_at", "gravatar_url" ], "title": "Contact" }, "ContactCustomField": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string" }, "options": { "type": [ "array", "null" ], "items": {} }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "name", "key", "type", "options", "required", "multiple", "featured", "sort_order", "created_at", "updated_at" ], "title": "ContactCustomField" }, "ContactExtraLabel": { "type": "string", "description": "What an extra email address or phone number on a contact is for. A row may also carry no label at all.\n", "enum": [ "home", "office", "mobile", "other" ], "title": "ContactExtraLabel" }, "ContactList": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "name", "description", "created_at", "updated_at" ], "title": "ContactList" }, "ContactStatus": { "type": "string", "description": "Whether a contact can still be emailed. Anything but `active` makes replies, new conversations and ticket confirmations to the address refuse unless the request passes `force: true`.\n", "enum": [ "active", "left", "bounced", "do_not_contact" ], "title": "ContactStatus" }, "Conversation": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "contact_id": { "type": [ "integer", "null" ] }, "agent_id": { "type": [ "integer", "null" ] }, "owner_id": { "type": [ "integer", "null" ] }, "status": { "$ref": "#/components/schemas/ConversationStatus" }, "subject": { "type": "string" }, "preview": { "type": [ "string", "null" ] }, "workspace_email": { "type": [ "string", "null" ] }, "is_spam": { "type": "boolean" }, "spam_reason": { "anyOf": [ { "$ref": "#/components/schemas/SpamReason" }, { "type": "null" } ] }, "from_machine_sender": { "type": "boolean" }, "is_read": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "sending_email": { "type": [ "string", "null" ] }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "waiting_on": { "anyOf": [ { "$ref": "#/components/schemas/WaitingOn" }, { "type": "null" } ] }, "waiting_on_since": { "type": [ "string", "null" ], "format": "date-time" }, "trashed_by": { "type": [ "integer", "null" ] } }, "required": [ "id", "workspace_id", "contact_id", "agent_id", "owner_id", "status", "subject", "preview", "workspace_email", "is_spam", "spam_reason", "from_machine_sender", "is_read", "archived_at", "sending_email", "last_message_at", "created_at", "updated_at", "deleted_at", "waiting_on", "waiting_on_since", "trashed_by" ], "title": "Conversation" }, "ConversationMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "conversation_id": { "type": "integer" }, "type": { "$ref": "#/components/schemas/ConversationMessageType" }, "sender_type": { "type": [ "string", "null" ] }, "sender_id": { "type": [ "integer", "null" ] }, "body": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "is_html": { "type": "boolean" }, "from_email": { "type": [ "string", "null" ] }, "from_name": { "type": [ "string", "null" ] }, "to_email": { "type": [ "string", "null" ] }, "delivered_to": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "cc_emails": { "type": [ "array", "null" ], "items": {} }, "message_id": { "type": [ "string", "null" ] }, "in_reply_to": { "type": [ "string", "null" ] }, "quote_source_message_id": { "type": [ "integer", "null" ] }, "provider": { "type": [ "string", "null" ] }, "provider_message_id": { "type": [ "string", "null" ] }, "dmarc_failed": { "type": "boolean" }, "delivery_status": { "anyOf": [ { "$ref": "#/components/schemas/DeliveryStatus" }, { "type": "null" } ] }, "delivery_status_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivery_detail": { "type": [ "string", "null" ] }, "dropped_recipients": { "type": [ "array", "null" ], "items": {} }, "is_draft": { "type": "boolean" }, "is_automated": { "type": "boolean" }, "is_auto_reply": { "type": "boolean" }, "raw_payload_path": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "sender_verified": { "type": [ "boolean", "null" ] }, "mentioned_user_ids": { "type": [ "array", "null" ], "items": {} }, "trashed_by": { "type": [ "integer", "null" ] }, "images_trusted": { "type": "boolean" }, "reply_to_unverified": { "type": "boolean" } }, "required": [ "id", "conversation_id", "type", "sender_type", "sender_id", "body", "text", "is_html", "from_email", "from_name", "to_email", "delivered_to", "reply_to", "cc_emails", "message_id", "in_reply_to", "quote_source_message_id", "provider", "provider_message_id", "dmarc_failed", "delivery_status", "delivery_status_at", "delivery_detail", "dropped_recipients", "is_draft", "is_automated", "is_auto_reply", "raw_payload_path", "created_at", "updated_at", "deleted_at", "sender_verified", "mentioned_user_ids", "trashed_by", "images_trusted", "reply_to_unverified" ], "title": "ConversationMessage" }, "ConversationMessageType": { "type": "string", "description": "What an inbox message is. `inbound` is mail the contact sent you, `outbound` is a reply delivered to them, and `internal_note` is a note for your own team: it is stored on the conversation and never sent anywhere.\n", "enum": [ "inbound", "outbound", "internal_note" ], "title": "ConversationMessageType" }, "ConversationStatus": { "type": "string", "enum": [ "open", "closed" ], "title": "ConversationStatus" }, "DeliveryStatus": { "type": "string", "description": "What became of an outbound message after it left PimiDesk, as reported by the sending provider. `null` means the message was handed over and no report has come back yet — most messages stay that way, since a provider only tells you what happened after the handoff. `failed` means the message was never sent: the send gave up for good, and `delivery_detail` says why. Resending the message clears it. Inbound messages never carry a value here.\n", "enum": [ "delivered", "bounced", "complained", "failed" ], "title": "DeliveryStatus" }, "EmailDraft": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "user_id": { "type": "integer" }, "channel": { "type": "string" }, "from_email": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "is_html": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": [ "string", "null" ] }, "cc": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "workspace_id", "user_id", "channel", "from_email", "subject", "body", "is_html", "created_at", "updated_at", "to", "cc" ], "title": "EmailDraft" }, "EmailPurpose": { "type": "string", "enum": [ "ticket", "inbox" ], "title": "EmailPurpose" }, "GithubLink": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "linkable_type": { "type": "string" }, "linkable_id": { "type": "integer" }, "owner": { "type": "string" }, "repo": { "type": "string" }, "number": { "type": "integer" }, "kind": { "$ref": "#/components/schemas/GithubLinkKind" }, "url": { "type": "string" }, "created_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "label": { "type": "string" } }, "required": [ "id", "workspace_id", "linkable_type", "linkable_id", "owner", "repo", "number", "kind", "url", "created_by", "created_at", "updated_at", "label" ], "title": "GithubLink" }, "GithubLinkKind": { "type": "string", "enum": [ "issue", "pull" ], "title": "GithubLinkKind" }, "LengthAwarePaginator": { "type": "object", "properties": { "current_page": { "type": "integer" }, "data": { "type": "string" }, "first_page_url": { "type": "string" }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer" }, "last_page_url": { "type": "string" }, "links": { "type": "object", "additionalProperties": {} }, "next_page_url": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "per_page": { "type": "integer" }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer" } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page", "last_page_url", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ], "title": "LengthAwarePaginator" }, "Link": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "url": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/LinkKind" }, "created_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "url", "title", "kind", "created_by", "created_at", "updated_at" ], "title": "Link" }, "LinkKind": { "type": "string", "description": "What a reference link points at: a GitHub issue, a GitHub pull request, or any other page. Read from the URL when the link is added; never chosen by the client.\n", "enum": [ "github_issue", "github_pull", "other" ], "title": "LinkKind" }, "MessageType": { "type": "string", "description": "What a ticket message is. `email` is correspondence with the contact — either something they sent in or a reply delivered to them. `internal_note` is a note for your own team: it is stored on the ticket and never sent anywhere.\n", "enum": [ "email", "internal_note" ], "title": "MessageType" }, "Organization": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "name", "created_at", "updated_at" ], "title": "Organization" }, "OrganizationCustomField": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "name": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string" }, "options": { "type": [ "array", "null" ], "items": {} }, "required": { "type": "boolean" }, "multiple": { "type": "boolean" }, "featured": { "type": "boolean" }, "sort_order": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "name", "key", "type", "options", "required", "multiple", "featured", "sort_order", "created_at", "updated_at" ], "title": "OrganizationCustomField" }, "Plan": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": "string" }, "paddle_price_id": { "type": [ "string", "null" ] }, "paddle_price_id_no_trial": { "type": [ "string", "null" ] }, "max_workspaces_per_user": { "type": "integer" }, "max_members": { "type": "integer" }, "max_emails": { "type": "integer" }, "max_domains": { "type": "integer" }, "max_contacts": { "type": [ "integer", "null" ] }, "max_tags": { "type": "integer" }, "max_canned_responses": { "type": "integer" }, "max_storage_mb": { "type": [ "integer", "null" ] }, "max_webhooks": { "type": [ "integer", "null" ] }, "max_automations": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_emails_per_hour": { "type": [ "integer", "null" ] }, "max_emails_per_day": { "type": [ "integer", "null" ] }, "is_public": { "type": "boolean" } }, "required": [ "id", "name", "slug", "description", "price", "paddle_price_id", "paddle_price_id_no_trial", "max_workspaces_per_user", "max_members", "max_emails", "max_domains", "max_contacts", "max_tags", "max_canned_responses", "max_storage_mb", "max_webhooks", "max_automations", "created_at", "updated_at", "max_emails_per_hour", "max_emails_per_day", "is_public" ], "title": "Plan" }, "ReceiveMethod": { "type": "string", "enum": [ "forwarding", "mx", "platform" ], "title": "ReceiveMethod" }, "SlaPolicy": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "priority": { "$ref": "#/components/schemas/TicketPriority" }, "first_response_minutes": { "type": [ "integer", "null" ] }, "resolution_minutes": { "type": [ "integer", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "priority", "first_response_minutes", "resolution_minutes", "is_active", "created_at", "updated_at" ], "title": "SlaPolicy" }, "SpamReason": { "type": "string", "description": "Why a ticket / conversation was flagged spam at intake by a sender block. NULL means \"not by a block\" — an SES verdict, an SPF/DKIM fail, an automation rule, or a human. `auto_block` is what makes a false-positive auto-ban findable in the spam views instead of buried.\n", "enum": [ "blocked_sender", "auto_block" ], "title": "SpamReason" }, "Tag": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "workspace_id": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "color", "workspace_id", "created_at", "updated_at" ], "title": "Tag" }, "ThreadSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "body": { "type": "string" }, "headline": { "type": "string" }, "covers_message_id": { "type": [ "integer", "null" ] }, "updated_by_id": { "type": [ "integer", "null" ] }, "via": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "body", "headline", "covers_message_id", "updated_by_id", "via", "created_at", "updated_at" ], "title": "ThreadSummary" }, "Ticket": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "workspace_email": { "type": [ "string", "null" ] }, "external_reference": { "type": [ "string", "null" ] }, "sending_email": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "agent_id": { "type": [ "integer", "null" ] }, "subject": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/TicketStatus" }, "priority": { "$ref": "#/components/schemas/TicketPriority" }, "is_spam": { "type": "boolean" }, "spam_reason": { "anyOf": [ { "$ref": "#/components/schemas/SpamReason" }, { "type": "null" } ] }, "from_machine_sender": { "type": "boolean" }, "is_read": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "first_response_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "waiting_on": { "anyOf": [ { "$ref": "#/components/schemas/WaitingOn" }, { "type": "null" } ] }, "waiting_on_since": { "type": [ "string", "null" ], "format": "date-time" }, "trashed_by": { "type": [ "integer", "null" ] }, "source": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "workspace_email", "external_reference", "sending_email", "contact_id", "agent_id", "subject", "description", "status", "priority", "is_spam", "spam_reason", "from_machine_sender", "is_read", "archived_at", "created_at", "updated_at", "closed_at", "first_response_at", "last_activity_at", "deleted_at", "waiting_on", "waiting_on_since", "trashed_by", "source" ], "title": "Ticket" }, "TicketActivity": { "type": "object", "properties": { "id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "user_id": { "type": [ "integer", "null" ] }, "action": { "type": "string" }, "properties": { "type": [ "array", "null" ], "items": {} }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "ticket_id", "user_id", "action", "properties", "created_at" ], "title": "TicketActivity" }, "TicketMessage": { "type": "object", "properties": { "id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "sender_type": { "type": [ "string", "null" ] }, "sender_id": { "type": [ "integer", "null" ] }, "message": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "is_html": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/MessageType" }, "from_email": { "type": [ "string", "null" ] }, "from_name": { "type": [ "string", "null" ] }, "to_email": { "type": [ "string", "null" ] }, "delivered_to": { "type": [ "string", "null" ] }, "reply_to": { "type": [ "string", "null" ] }, "cc_emails": { "type": [ "array", "null" ], "items": {} }, "mentioned_user_ids": { "type": [ "array", "null" ], "items": {} }, "raw_payload_path": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "in_reply_to": { "type": [ "string", "null" ] }, "quote_source_message_id": { "type": [ "integer", "null" ] }, "provider": { "type": [ "string", "null" ] }, "provider_message_id": { "type": [ "string", "null" ] }, "dmarc_failed": { "type": "boolean" }, "delivery_status": { "anyOf": [ { "$ref": "#/components/schemas/DeliveryStatus" }, { "type": "null" } ] }, "delivery_status_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivery_detail": { "type": [ "string", "null" ] }, "dropped_recipients": { "type": [ "array", "null" ], "items": {} }, "is_draft": { "type": "boolean" }, "is_automated": { "type": "boolean" }, "is_auto_reply": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "sender_verified": { "type": [ "boolean", "null" ] }, "trashed_by": { "type": [ "integer", "null" ] }, "images_trusted": { "type": "boolean" }, "reply_to_unverified": { "type": "boolean" } }, "required": [ "id", "ticket_id", "sender_type", "sender_id", "message", "text", "is_html", "type", "from_email", "from_name", "to_email", "delivered_to", "reply_to", "cc_emails", "mentioned_user_ids", "raw_payload_path", "message_id", "in_reply_to", "quote_source_message_id", "provider", "provider_message_id", "dmarc_failed", "delivery_status", "delivery_status_at", "delivery_detail", "dropped_recipients", "is_draft", "is_automated", "is_auto_reply", "created_at", "updated_at", "deleted_at", "sender_verified", "trashed_by", "images_trusted", "reply_to_unverified" ], "title": "TicketMessage" }, "TicketPriority": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "TicketPriority" }, "TicketStatus": { "type": "string", "enum": [ "open", "in_progress", "pending", "closed" ], "title": "TicketStatus" }, "TrustedSender": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "email": { "type": "string" }, "match_type": { "$ref": "#/components/schemas/BlockMatchType" }, "created_by": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "email", "match_type", "created_by", "created_at", "updated_at" ], "title": "TrustedSender" }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "pending_email": { "type": [ "string", "null" ] }, "pending_email_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "banned_at": { "type": [ "string", "null" ], "format": "date-time" }, "ban_reason": { "type": [ "string", "null" ] }, "banned_by": { "type": [ "integer", "null" ] }, "plan_id": { "type": [ "integer", "null" ] }, "has_used_trial": { "type": "boolean" }, "max_workspaces": { "type": [ "integer", "null" ] }, "onboarding_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "quote_replies": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "gravatar_url": { "type": "string" }, "resolved_display_name": { "type": "string" } }, "required": [ "id", "name", "email", "role", "email_verified_at", "pending_email", "pending_email_requested_at", "banned_at", "ban_reason", "banned_by", "plan_id", "has_used_trial", "max_workspaces", "onboarding_completed_at", "quote_replies", "created_at", "updated_at", "display_name", "gravatar_url", "resolved_display_name" ], "title": "User" }, "UserRole": { "type": "string", "enum": [ "admin", "customer" ], "title": "UserRole" }, "WaitingOn": { "type": "string", "description": "Who owes the next message on a ticket or conversation. `us` means the customer wrote last and is waiting on a reply; `customer` means you replied and are waiting on them. Null means nobody: a closed or spam thread, one marked \"no * reply needed\", or one with no message that counts yet. Notes, drafts, automatic replies, spam and mail whose sender could not be verified do not count, and a shared or personal inbox conversation waits on `us` only after a reply of yours. It is separate from `status`, which is the workflow.\n", "enum": [ "us", "customer" ], "title": "WaitingOn" }, "Workspace": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_by": { "type": [ "integer", "null" ] }, "plan_id": { "type": [ "integer", "null" ] }, "max_members": { "type": [ "integer", "null" ] }, "max_emails": { "type": [ "integer", "null" ] }, "max_domains": { "type": [ "integer", "null" ] }, "max_contacts": { "type": [ "integer", "null" ] }, "max_tags": { "type": [ "integer", "null" ] }, "max_canned_responses": { "type": [ "integer", "null" ] }, "max_storage_mb": { "type": [ "integer", "null" ] }, "max_webhooks": { "type": [ "integer", "null" ] }, "max_automations": { "type": [ "integer", "null" ] }, "tickets_enabled": { "type": "boolean" }, "shared_inbox_enabled": { "type": "boolean" }, "personal_inbox_enabled": { "type": "boolean" }, "send_confirmation_email": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "widget_enabled": { "type": "boolean" }, "live_chat_enabled": { "type": "boolean" }, "max_emails_per_hour": { "type": [ "integer", "null" ] }, "max_emails_per_day": { "type": [ "integer", "null" ] }, "is_active": { "type": "string" }, "is_on_trial": { "type": "string" }, "has_sendable_inbox_email": { "type": "string" } }, "required": [ "id", "name", "slug", "created_by", "plan_id", "max_members", "max_emails", "max_domains", "max_contacts", "max_tags", "max_canned_responses", "max_storage_mb", "max_webhooks", "max_automations", "tickets_enabled", "shared_inbox_enabled", "personal_inbox_enabled", "send_confirmation_email", "created_at", "updated_at", "widget_enabled", "live_chat_enabled", "max_emails_per_hour", "max_emails_per_day", "is_active", "is_on_trial", "has_sendable_inbox_email" ], "title": "Workspace" }, "WorkspaceEmail": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "workspace_domain_id": { "type": [ "integer", "null" ] }, "user_id": { "type": [ "integer", "null" ] }, "email": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/EmailPurpose" }, "receive_method": { "$ref": "#/components/schemas/ReceiveMethod" }, "sender_name": { "type": [ "string", "null" ] }, "can_send": { "type": "boolean" }, "forwarding_address": { "type": [ "string", "null" ] }, "incoming_email_count": { "type": "integer" }, "outgoing_email_count": { "type": "integer" }, "last_email_received_at": { "type": [ "string", "null" ] }, "last_email_sent_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "can_send_resolved": { "type": "string" }, "can_receive_resolved": { "type": "string" } }, "required": [ "id", "workspace_id", "workspace_domain_id", "user_id", "email", "purpose", "receive_method", "sender_name", "can_send", "forwarding_address", "incoming_email_count", "outgoing_email_count", "last_email_received_at", "last_email_sent_at", "created_at", "updated_at", "can_send_resolved", "can_receive_resolved" ], "title": "WorkspaceEmail" }, "WorkspaceInvitation": { "type": "object", "properties": { "id": { "type": "integer" }, "workspace_id": { "type": "integer" }, "invited_by": { "type": "integer" }, "email": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "workspace_id", "invited_by", "email", "role", "status", "expires_at", "created_at", "updated_at" ], "title": "WorkspaceInvitation" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ContactNotSendableException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }