{ "openapi": "3.0.3", "info": { "title": "HESK API", "description": "REST API for HESK 3.7.11 help desk at support.joeysbox.com.\n\n**Security model:** Every API token is bound to a HESK staff account and inherits that account's categories, feature privileges, and admin flag (including full administrative access when the bound user is an admin).\n\n**Architecture:** The API talks primarily to the HESK MySQL database. It does **not** modify HESK source code. Outbound notification emails are sent by bootstrapping HESK's own email functions when needed.\n\n**Portal:** Sign in at the API host root to create and revoke tokens. Administrators can create tokens for any staff user.\n\n**Ticket links:** Related tickets can be associated with `GET/POST /v1/tickets/{id}/links` and `DELETE /v1/tickets/{id}/links/{linkedId}` (requires `can_link_tickets` to create/remove).", "version": "1.1.0", "contact": { "name": "Joey's Box Support", "url": "https://support.joeysbox.com" } }, "servers": [ { "url": "https://api-support.joeysbox.com/v1", "description": "Production" } ], "tags": [ { "name": "Auth", "description": "Obtain API tokens with staff credentials" }, { "name": "Me", "description": "Current token identity and reference data" }, { "name": "Tokens", "description": "Manage long-lived API tokens" }, { "name": "Tickets", "description": "Ticket CRUD, replies, and notes" }, { "name": "Ticket links", "description": "Link related help-desk tickets together (same as HESK admin “linked tickets”). Requires the `can_link_tickets` privilege to create or remove links. Listing requires view access to the source ticket; linked tickets the caller cannot view are omitted from results." }, { "name": "Categories", "description": "Help desk categories / departments" }, { "name": "Users", "description": "Staff users" }, { "name": "Customers", "description": "Customer contacts" }, { "name": "Knowledgebase", "description": "KB categories and articles" }, { "name": "Canned replies", "description": "Standard (canned) replies" }, { "name": "Health", "description": "Service health" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "security": [], "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "Database unavailable" } } } }, "/auth/token": { "post": { "tags": [ "Auth" ], "summary": "Create token with username/password", "description": "Exchanges HESK staff credentials for a new API token. Prefer the web portal for interactive use.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "example": "admin" }, "password": { "type": "string", "format": "password" }, "name": { "type": "string", "example": "CI bot" }, "ttl_days": { "type": "integer", "nullable": true, "example": 90 } } } } } }, "responses": { "201": { "description": "Token created (plaintext shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/me": { "get": { "tags": [ "Me" ], "summary": "Current user and privileges", "responses": { "200": { "description": "Authenticated staff identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/privileges": { "get": { "tags": [ "Me" ], "summary": "List privilege catalog and mine", "responses": { "200": { "description": "Privilege lists" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/statuses": { "get": { "tags": [ "Me" ], "summary": "Ticket statuses", "responses": { "200": { "description": "Status list (defaults + custom)" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/priorities": { "get": { "tags": [ "Me" ], "summary": "Ticket priorities", "responses": { "200": { "description": "Priority list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List my tokens", "parameters": [ { "name": "user_id", "in": "query", "schema": { "type": "integer" }, "description": "Admin / can_man_users: list another user's tokens" }, { "name": "include_revoked", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Token metadata (secrets never returned)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TokenMeta" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Tokens" ], "summary": "Create API token", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Zapier" }, "ttl_days": { "type": "integer", "nullable": true }, "user_id": { "type": "integer", "description": "Admin / can_man_users: bind token to another staff user" } } } } } }, "responses": { "201": { "description": "Created; plaintext token returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Token limit reached" } } } }, "/tokens/{id}": { "delete": { "tags": [ "Tokens" ], "summary": "Revoke token", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "description": "Results are filtered by the bound user's category and ownership privileges (same rules as HESK staff UI).", "parameters": [ { "name": "status", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "description": "Status id or comma-separated list" }, { "name": "category", "in": "query", "schema": { "type": "integer" } }, { "name": "owner", "in": "query", "schema": { "type": "integer" }, "description": "0 = unassigned" }, { "name": "priority", "in": "query", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search subject, message, trackid, customer" }, { "name": "trackid", "in": "query", "schema": { "type": "string" } }, { "name": "archived", "in": "query", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "id", "lastchange", "dt", "priority", "status", "subject", "due_date" ], "default": "lastchange" } }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated ticket list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Tickets" ], "summary": "Create ticket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tickets/{id}": { "get": { "tags": [ "Tickets" ], "summary": "Get ticket by id or trackid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric id or tracking id (e.g. 4ZH-HNG-UVT8)", "example": "4ZH-HNG-UVT8" } ], "responses": { "200": { "description": "Ticket detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Tickets" ], "summary": "Update ticket fields", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketUpdate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Tickets" ], "summary": "Update ticket fields (alias of PATCH)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketUpdate" } } } }, "responses": { "200": { "description": "Updated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": [ "Tickets" ], "summary": "Delete ticket", "description": "Requires `can_del_tickets`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets/{id}/replies": { "get": { "tags": [ "Tickets" ], "summary": "List replies", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replies", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reply" } } } } } } } } }, "post": { "tags": [ "Tickets" ], "summary": "Add staff reply", "description": "Requires `can_reply_tickets`. Optionally notifies the customer via HESK email templates.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "integer", "default": 2, "description": "2 = staff replied, 3 = resolved (needs can_resolve)" }, "notify": { "type": "boolean", "default": true }, "append_signature": { "type": "boolean", "default": false }, "assign_self": { "type": "boolean", "default": false, "description": "If ticket unassigned and can_assign_self, assign to token user" } } } } } }, "responses": { "201": { "description": "Reply created" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Ticket locked" } } } }, "/tickets/{id}/notes": { "get": { "tags": [ "Tickets" ], "summary": "List internal notes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notes" } } }, "post": { "tags": [ "Tickets" ], "summary": "Add internal note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } } } }, "responses": { "201": { "description": "Note created" } } } }, "/tickets/{id}/notes/{noteId}": { "delete": { "tags": [ "Tickets" ], "summary": "Delete note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/categories": { "get": { "tags": [ "Categories" ], "summary": "List categories", "responses": { "200": { "description": "Categories visible to the user" } } }, "post": { "tags": [ "Categories" ], "summary": "Create category", "description": "Requires `can_man_cat`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "autoassign": { "type": "boolean" }, "private": { "type": "boolean" }, "priority": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/categories/{id}": { "get": { "tags": [ "Categories" ], "summary": "Get category", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Categories" ], "summary": "Update category", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete category", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "409": { "description": "Has tickets or default category" } } } }, "/users": { "get": { "tags": [ "Users" ], "summary": "List staff users", "description": "Requires admin, `can_view_users`, `can_man_users`, or `can_assign_others`.", "responses": { "200": { "description": "Staff list" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get staff user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Customer list" } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "language": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" }, "409": { "description": "Email already exists" } } } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Customer" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Requires `can_man_customers` or admin.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated" } } } }, "/kb/categories": { "get": { "tags": [ "Knowledgebase" ], "summary": "List KB categories", "responses": { "200": { "description": "KB categories" } } } }, "/kb/articles": { "get": { "tags": [ "Knowledgebase" ], "summary": "List KB articles", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "schema": { "type": "integer" }, "description": "0 public, 1 private, 2 draft" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Articles" } } }, "post": { "tags": [ "Knowledgebase" ], "summary": "Create article", "description": "Requires `can_man_kb` or admin.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "category_id" ], "properties": { "subject": { "type": "string" }, "content": { "type": "string" }, "category_id": { "type": "integer" }, "keywords": { "type": "string" }, "type": { "type": "integer", "default": 0 }, "html": { "type": "boolean" }, "sticky": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/kb/articles/{id}": { "get": { "tags": [ "Knowledgebase" ], "summary": "Get article", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Article" } } }, "patch": { "tags": [ "Knowledgebase" ], "summary": "Update article", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Knowledgebase" ], "summary": "Delete article", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/canned-replies": { "get": { "tags": [ "Canned replies" ], "summary": "List canned replies", "responses": { "200": { "description": "Canned replies" } } }, "post": { "tags": [ "Canned replies" ], "summary": "Create canned reply", "description": "Requires `can_man_canned` or admin.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "message" ], "properties": { "title": { "type": "string" }, "message": { "type": "string" }, "message_html": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/canned-replies/{id}": { "delete": { "tags": [ "Canned replies" ], "summary": "Delete canned reply", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/tickets/{id}/links": { "get": { "tags": [ "Ticket links", "Tickets" ], "summary": "List tickets linked to this ticket", "description": "Returns links involving this ticket. Each item includes `link_id`, `linked_at`, and a summary of the other ticket.\n\n**Permissions:** `can_view_tickets` plus normal ticket visibility for the source ticket. Linked tickets the caller cannot view are omitted.\n\nThe same summary list appears on `GET /tickets/{id}` as the `links` array.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Numeric ticket id or tracking id (e.g. 4ZH-HNG-UVT8)", "example": "4ZH-HNG-UVT8" } ], "responses": { "200": { "description": "Linked tickets", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketLink" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Ticket links", "Tickets" ], "summary": "Link another ticket to this one", "description": "Creates a bidirectional association between this ticket and another (stored in HESK `linked_tickets`). Mirrors the HESK admin “Link ticket” action.\n\n**Permissions:** `can_link_tickets`, and view access to **both** tickets.\n\n**Rules:**\n- Target may be identified by numeric id or tracking id\n- Cannot link a ticket to itself\n- Duplicate links return **409 conflict**\n- A history line is appended on the source ticket\n- Linking does not merge tickets or change status/owner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source ticket id or trackid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketLinkCreate" }, "examples": { "by_trackid": { "summary": "Link by tracking ID", "value": { "trackid": "G29-E41-8TH9" } }, "by_id": { "summary": "Link by numeric id", "value": { "ticket_id": 12 } }, "alias": { "summary": "Using linked_ticket alias", "value": { "linked_ticket": "G29-E41-8TH9" } } } } } }, "responses": { "201": { "description": "Link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketLinkCreated" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Tickets are already linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tickets/{id}/links/{linkedId}": { "delete": { "tags": [ "Ticket links", "Tickets" ], "summary": "Unlink a ticket", "description": "Removes the association between this ticket and another.\n\n`linkedId` may be either:\n- the **link row id** (`link_id` from list/create responses), or\n- the **other ticket’s** numeric id or tracking id\n\n**Permissions:** `can_link_tickets`, view access to both tickets involved.\nA history line is appended on the source ticket.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source ticket id or trackid" }, { "name": "linkedId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Link id, or other ticket id/trackid", "example": "G29-E41-8TH9" } ], "responses": { "204": { "description": "Link removed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API token", "description": "Token from the portal or POST /v1/auth/token. Format: `hsk_…`" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to Authorization Bearer" } }, "responses": { "Unauthorized": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but insufficient privileges", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Invalid request body or parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "forbidden" }, "message": { "type": "string" } } } } }, "Health": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "hesk-api" }, "version": { "type": "string" }, "hesk_version": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "database": { "type": "string", "example": "connected" } } }, "Me": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "is_admin": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "integer" } }, "privileges": { "type": "array", "items": { "type": "string" }, "description": "Feature privileges; `[\"*\"]` when is_admin" }, "token": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "TokenMeta": { "type": "object", "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "token_prefix": { "type": "string", "example": "hsk_AbCdEf…" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_ip": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" } } }, "TokenCreateResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Full secret — only returned at creation time" }, "token_meta": { "$ref": "#/components/schemas/TokenMeta" }, "warning": { "type": "string" } } } } }, "TicketSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "trackid": { "type": "string", "example": "4ZH-HNG-UVT8" }, "subject": { "type": "string" }, "status": { "type": "integer" }, "priority": { "type": "integer" }, "category": { "type": "integer" }, "owner": { "type": "integer" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string" }, "replies": { "type": "integer" }, "staff_replies": { "type": "integer" }, "locked": { "type": "boolean" }, "archived": { "type": "boolean" }, "due_date": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": "string", "format": "date-time", "nullable": true }, "last_replier": { "type": "string", "enum": [ "staff", "customer" ] } } }, "Ticket": { "allOf": [ { "$ref": "#/components/schemas/TicketSummary" }, { "type": "object", "properties": { "message": { "type": "string" }, "message_html": { "type": "string" }, "ip": { "type": "string" }, "opened_by": { "type": "integer", "nullable": true }, "closed_by": { "type": "integer", "nullable": true }, "assigned_by": { "type": "integer", "nullable": true }, "time_worked": { "type": "string" }, "language": { "type": "string", "nullable": true }, "history": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": { "type": "string" } }, "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "REQUESTER", "FOLLOWER" ] } } } }, "collaborators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } } }, "links": { "type": "array", "description": "Tickets linked to this one (permission-filtered). Manage via /tickets/{id}/links.", "items": { "$ref": "#/components/schemas/TicketLinkSummary" } } } } ] }, "TicketList": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketSummary" } } } }, "TicketCreate": { "type": "object", "required": [ "subject", "message", "category" ], "properties": { "subject": { "type": "string" }, "message": { "type": "string" }, "category": { "type": "integer" }, "priority": { "type": "integer", "default": 3, "description": "Priority id from GET /v1/priorities (default 0–3). Invalid values return 422.", "minimum": 0, "maximum": 255 }, "status": { "type": "integer", "default": 0 }, "customer_id": { "type": "integer", "description": "Existing customer id. If set, name/email are taken from that customer." }, "customer_name": { "type": "string", "description": "Required when customer_id is not set." }, "customer_email": { "type": "string" }, "name": { "type": "string", "description": "Alias for customer_name" }, "email": { "type": "string", "description": "Alias for customer_email" }, "owner": { "type": "integer", "description": "Staff user id; 0 unassigned" }, "due_date": { "type": "string", "format": "date-time" }, "notify": { "type": "boolean", "default": true, "description": "Send HESK notification emails (customer + staff). Defaults to true. Failures sending mail do not fail ticket creation." }, "follower_ids": { "type": "array", "items": { "type": "integer" } }, "custom1": { "type": "string" } }, "additionalProperties": true, "description": "Create a ticket. Provide either `customer_id` (existing customer) or `customer_name` (and optional `customer_email` / `name` / `email` aliases). When `customer_id` is omitted, `customer_name` is required.", "anyOf": [ { "required": [ "customer_id" ] }, { "required": [ "customer_name" ] }, { "required": [ "name" ] } ] }, "TicketUpdate": { "type": "object", "properties": { "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "priority": { "type": "integer" }, "category": { "type": "integer" }, "owner": { "type": "integer" }, "due_date": { "type": "string", "nullable": true }, "locked": { "type": "boolean" }, "archived": { "type": "boolean" }, "notify": { "type": "boolean", "default": true } }, "additionalProperties": true }, "Reply": { "type": "object", "properties": { "id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "message": { "type": "string" }, "message_html": { "type": "string" }, "staff_id": { "type": "integer" }, "customer_id": { "type": "integer", "nullable": true }, "is_staff": { "type": "boolean" }, "read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "TicketLink": { "type": "object", "properties": { "link_id": { "type": "integer", "description": "Row id in hesk_linked_tickets" }, "linked_at": { "type": "string", "format": "date-time", "nullable": true }, "ticket": { "$ref": "#/components/schemas/TicketSummary" } } }, "TicketLinkCreate": { "type": "object", "description": "Identify the ticket to link. Provide exactly one of the fields (aliases accepted). Values may be a numeric ticket id or a tracking id.", "properties": { "ticket_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Numeric id or trackid of the ticket to link", "example": 12 }, "trackid": { "type": "string", "description": "Tracking id of the ticket to link", "example": "G29-E41-8TH9" }, "linked_ticket": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Alias for ticket_id / trackid" }, "linked_ticket_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Alias for ticket_id" }, "target": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Alias for ticket_id / trackid" } } }, "TicketLinkCreated": { "type": "object", "properties": { "link_id": { "type": "integer" }, "ticket_id1": { "type": "integer" }, "ticket_id2": { "type": "integer" }, "source_ticket_id": { "type": "integer" }, "linked_ticket_id": { "type": "integer" }, "linked_trackid": { "type": "string" }, "linked_subject": { "type": "string" }, "linked_at": { "type": "string", "format": "date-time", "nullable": true }, "ticket": { "$ref": "#/components/schemas/TicketSummary" } } }, "TicketLinkSummary": { "type": "object", "description": "Compact link entry embedded on GET /tickets/{id}", "properties": { "link_id": { "type": "integer" }, "ticket_id": { "type": "integer" }, "trackid": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "integer" }, "category": { "type": "integer" }, "linked_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ] }