{ "openapi": "3.0.3", "info": { "title": "sondahub Helpdesk API", "version": "0.6.1", "description": "A support desk: tickets, messages, agents, customers, SLAs — the state-machine one.\n\nTwo thousand tickets with their message threads, twenty-five agents in four teams and three hundred customer companies. A ticket moves open → pending → resolved → closed; PATCH its status and the hub checks the transition and stamps the timestamps.\n\nNo keys, no accounts. Writes (POST, PUT, PATCH, DELETE) are validated and answered exactly as a real server would answer them, then forgotten: sondahub stores nothing, and every such answer says so in _note and in the X-Sondahub-Write: simulated header. Every list takes page, limit, sort, q, fields and expand, plus one filter per field with the operators _ne _gt _gte _lt _lte _like _in.", "contact": { "name": "sondahub", "url": "https://api.sondahub.com" } }, "servers": [ { "url": "https://api.sondahub.com" } ], "tags": [ { "name": "teams", "description": "Support teams." }, { "name": "agents", "description": "The people answering tickets." }, { "name": "customers", "description": "Companies with a support contract." }, { "name": "tickets", "description": "A support request. Allowed status moves: open → pending | resolved; pending → open | resolved; resolved → closed | open; closed → open (reopen). Anything else answers 422." }, { "name": "messages", "description": "The thread on a ticket, in order. author_type says who wrote it." } ], "paths": { "/v1/helpdesk/teams": { "get": { "tags": [ "teams" ], "summary": "List teams", "operationId": "list_teams", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: agents.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "name", "in": "query", "required": false, "description": "Filter: name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "Tier 1" } }, { "name": "slug", "in": "query", "required": false, "description": "Filter: slug equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "timezone", "in": "query", "required": false, "description": "Filter: timezone equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "hours", "in": "query", "required": false, "description": "Filter: hours equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "24/7" } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "teams" ], "summary": "Create a team", "operationId": "create_team", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/teams/{id}": { "get": { "tags": [ "teams" ], "summary": "Get a team", "operationId": "get_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "teams" ], "summary": "Replace a team", "operationId": "replace_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "teams" ], "summary": "Update part of a team", "operationId": "update_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "teams" ], "summary": "Delete a team", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/teams/{id}/agents": { "get": { "tags": [ "teams" ], "summary": "The agents of a team", "operationId": "team_agents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/agents": { "get": { "tags": [ "agents" ], "summary": "List agents", "operationId": "list_agents", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: team, tickets.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "name", "in": "query", "required": false, "description": "Filter: name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Filter: email equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string" } }, { "name": "team_id", "in": "query", "required": false, "description": "Filter: team_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "description": "The id of a team." } }, { "name": "role", "in": "query", "required": false, "description": "Filter: role equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "agent", "senior", "lead", "admin" ], "nullable": true, "example": "agent" } }, { "name": "status", "in": "query", "required": false, "description": "Filter: status equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "available", "busy", "away", "offline" ], "nullable": true, "example": "available" } }, { "name": "open_tickets", "in": "query", "required": false, "description": "Filter: open_tickets equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "readOnly": true } }, { "name": "rating", "in": "query", "required": false, "description": "Filter: rating equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "number", "nullable": true, "readOnly": true } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "agents" ], "summary": "Create a agent", "operationId": "create_agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/agents/{id}": { "get": { "tags": [ "agents" ], "summary": "Get a agent", "operationId": "get_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "agents" ], "summary": "Replace a agent", "operationId": "replace_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "agents" ], "summary": "Update part of a agent", "operationId": "update_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "agents" ], "summary": "Delete a agent", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/agents/{id}/team": { "get": { "tags": [ "agents" ], "summary": "The team of a agent", "operationId": "agent_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/agents/{id}/tickets": { "get": { "tags": [ "agents" ], "summary": "The tickets of a agent", "operationId": "agent_tickets", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/customers": { "get": { "tags": [ "customers" ], "summary": "List customers", "operationId": "list_customers", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: tickets.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "name", "in": "query", "required": false, "description": "Filter: name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "Blue Systems Inc." } }, { "name": "domain", "in": "query", "required": false, "description": "Filter: domain equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "bluesystems.example" } }, { "name": "plan", "in": "query", "required": false, "description": "Filter: plan equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "free", "starter", "business", "enterprise" ], "nullable": true, "example": "free" } }, { "name": "contact_name", "in": "query", "required": false, "description": "Filter: contact_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "contact_email", "in": "query", "required": false, "description": "Filter: contact_email equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "sla_hours", "in": "query", "required": false, "description": "Filter: sla_hours equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "First response target, hours." } }, { "name": "open_tickets", "in": "query", "required": false, "description": "Filter: open_tickets equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "readOnly": true } }, { "name": "satisfaction", "in": "query", "required": false, "description": "Filter: satisfaction equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "number", "nullable": true, "description": "Average CSAT, 1–5.", "readOnly": true } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "customers" ], "summary": "Create a customer", "operationId": "create_customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/customers/{id}": { "get": { "tags": [ "customers" ], "summary": "Get a customer", "operationId": "get_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "customers" ], "summary": "Replace a customer", "operationId": "replace_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "customers" ], "summary": "Update part of a customer", "operationId": "update_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "customers" ], "summary": "Delete a customer", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/customers/{id}/tickets": { "get": { "tags": [ "customers" ], "summary": "The tickets of a customer", "operationId": "customer_tickets", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets": { "get": { "tags": [ "tickets" ], "summary": "List tickets", "operationId": "list_tickets", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: -created_at.", "schema": { "type": "string", "example": "-created_at" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: customer, assignee, team, messages.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "number", "in": "query", "required": false, "description": "Filter: number equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "HD-10042", "readOnly": true } }, { "name": "subject", "in": "query", "required": false, "description": "Filter: subject equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter: status equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ], "nullable": true, "example": "open" } }, { "name": "priority", "in": "query", "required": false, "description": "Filter: priority equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "nullable": true, "example": "low" } }, { "name": "category", "in": "query", "required": false, "description": "Filter: category equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "billing", "account", "bug", "feature", "howto" ], "nullable": true, "example": "billing" } }, { "name": "channel", "in": "query", "required": false, "description": "Filter: channel equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "email", "chat", "phone", "web", "api" ], "nullable": true, "example": "email" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filter: customer_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "description": "The id of a customer." } }, { "name": "requester_email", "in": "query", "required": false, "description": "Filter: requester_email equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "assignee_id", "in": "query", "required": false, "description": "Filter: assignee_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "The id of a agent." } }, { "name": "team_id", "in": "query", "required": false, "description": "Filter: team_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "The id of a team." } }, { "name": "first_response_at", "in": "query", "required": false, "description": "Filter: first_response_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, { "name": "resolved_at", "in": "query", "required": false, "description": "Filter: resolved_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, { "name": "closed_at", "in": "query", "required": false, "description": "Filter: closed_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, { "name": "due_at", "in": "query", "required": false, "description": "Filter: due_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true } }, { "name": "sla_breached", "in": "query", "required": false, "description": "Filter: sla_breached equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "boolean", "nullable": true, "readOnly": true } }, { "name": "satisfaction", "in": "query", "required": false, "description": "Filter: satisfaction equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "CSAT given at close.", "minimum": 1, "maximum": 5 } }, { "name": "message_count", "in": "query", "required": false, "description": "Filter: message_count equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "readOnly": true } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "tickets" ], "summary": "Create a ticket", "operationId": "create_ticket", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets/{id}": { "get": { "tags": [ "tickets" ], "summary": "Get a ticket", "operationId": "get_ticket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "tickets" ], "summary": "Replace a ticket", "operationId": "replace_ticket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "tickets" ], "summary": "Update part of a ticket", "operationId": "update_ticket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "tickets" ], "summary": "Delete a ticket", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_ticket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets/{id}/customer": { "get": { "tags": [ "tickets" ], "summary": "The customer of a ticket", "operationId": "ticket_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets/{id}/assignee": { "get": { "tags": [ "tickets" ], "summary": "The assignee of a ticket", "operationId": "ticket_assignee", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets/{id}/team": { "get": { "tags": [ "tickets" ], "summary": "The team of a ticket", "operationId": "ticket_team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/tickets/{id}/messages": { "get": { "tags": [ "tickets" ], "summary": "The messages of a ticket", "operationId": "ticket_messages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: -created_at.", "schema": { "type": "string", "example": "-created_at" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/messages": { "get": { "tags": [ "messages" ], "summary": "List messages", "operationId": "list_messages", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: ticket, author.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "ticket_id", "in": "query", "required": false, "description": "Filter: ticket_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "description": "The id of a ticket." } }, { "name": "author_type", "in": "query", "required": false, "description": "Filter: author_type equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "customer", "agent", "system" ], "example": "customer" } }, { "name": "author_id", "in": "query", "required": false, "description": "Filter: author_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "The agent, when author_type is agent. The id of a agent." } }, { "name": "author_name", "in": "query", "required": false, "description": "Filter: author_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "internal", "in": "query", "required": false, "description": "Filter: internal equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "boolean", "nullable": true, "description": "A private note the customer does not see." } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "messages" ], "summary": "Create a message", "operationId": "create_message", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/messages/{id}": { "get": { "tags": [ "messages" ], "summary": "Get a message", "operationId": "get_message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "messages" ], "summary": "Replace a message", "operationId": "replace_message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "messages" ], "summary": "Update part of a message", "operationId": "update_message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "messages" ], "summary": "Delete a message", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_message", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/messages/{id}/ticket": { "get": { "tags": [ "messages" ], "summary": "The ticket of a message", "operationId": "message_ticket", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/helpdesk/messages/{id}/author": { "get": { "tags": [ "messages" ], "summary": "The author of a message", "operationId": "message_author", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "code", "message" ] } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "Team": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "name": { "type": "string", "example": "Tier 1" }, "slug": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "hours": { "type": "string", "nullable": true, "example": "24/7" } }, "required": [ "id", "created_at", "updated_at", "name" ] }, "TeamInput": { "type": "object", "properties": { "name": { "type": "string", "example": "Tier 1" }, "slug": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "hours": { "type": "string", "nullable": true, "example": "24/7" } }, "required": [ "name" ], "example": { "name": "Tier 1", "hours": "24/7" } }, "TeamList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Agent": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "name": { "type": "string" }, "email": { "type": "string" }, "team_id": { "type": "integer", "description": "The id of a team." }, "role": { "type": "string", "enum": [ "agent", "senior", "lead", "admin" ], "nullable": true, "example": "agent" }, "status": { "type": "string", "enum": [ "available", "busy", "away", "offline" ], "nullable": true, "example": "available" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Shape: string[]" }, "open_tickets": { "type": "integer", "nullable": true, "readOnly": true }, "rating": { "type": "number", "nullable": true, "readOnly": true } }, "required": [ "id", "created_at", "updated_at", "name", "email", "team_id", "open_tickets", "rating" ] }, "AgentInput": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "team_id": { "type": "integer", "description": "The id of a team." }, "role": { "type": "string", "enum": [ "agent", "senior", "lead", "admin" ], "nullable": true, "example": "agent" }, "status": { "type": "string", "enum": [ "available", "busy", "away", "offline" ], "nullable": true, "example": "available" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Shape: string[]" } }, "required": [ "name", "email", "team_id" ], "example": { "name": "A name", "email": "A email", "team_id": 1, "role": "agent", "status": "available" } }, "AgentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "name": { "type": "string", "example": "Blue Systems Inc." }, "domain": { "type": "string", "nullable": true, "example": "bluesystems.example" }, "plan": { "type": "string", "enum": [ "free", "starter", "business", "enterprise" ], "nullable": true, "example": "free" }, "contact_name": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true }, "sla_hours": { "type": "integer", "nullable": true, "description": "First response target, hours." }, "open_tickets": { "type": "integer", "nullable": true, "readOnly": true }, "satisfaction": { "type": "number", "nullable": true, "description": "Average CSAT, 1–5.", "readOnly": true } }, "required": [ "id", "created_at", "updated_at", "name", "open_tickets", "satisfaction" ] }, "CustomerInput": { "type": "object", "properties": { "name": { "type": "string", "example": "Blue Systems Inc." }, "domain": { "type": "string", "nullable": true, "example": "bluesystems.example" }, "plan": { "type": "string", "enum": [ "free", "starter", "business", "enterprise" ], "nullable": true, "example": "free" }, "contact_name": { "type": "string", "nullable": true }, "contact_email": { "type": "string", "nullable": true }, "sla_hours": { "type": "integer", "nullable": true, "description": "First response target, hours." } }, "required": [ "name" ], "example": { "name": "Blue Systems Inc.", "domain": "bluesystems.example", "plan": "free" } }, "CustomerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Ticket": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "number": { "type": "string", "nullable": true, "example": "HD-10042", "readOnly": true }, "subject": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ], "nullable": true, "example": "open" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "nullable": true, "example": "low" }, "category": { "type": "string", "enum": [ "billing", "account", "bug", "feature", "howto" ], "nullable": true, "example": "billing" }, "channel": { "type": "string", "enum": [ "email", "chat", "phone", "web", "api" ], "nullable": true, "example": "email" }, "customer_id": { "type": "integer", "description": "The id of a customer." }, "requester_email": { "type": "string", "nullable": true }, "assignee_id": { "type": "integer", "nullable": true, "description": "The id of a agent." }, "team_id": { "type": "integer", "nullable": true, "description": "The id of a team." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Shape: string[]" }, "first_response_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "closed_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "sla_breached": { "type": "boolean", "nullable": true, "readOnly": true }, "satisfaction": { "type": "integer", "nullable": true, "description": "CSAT given at close.", "minimum": 1, "maximum": 5 }, "message_count": { "type": "integer", "nullable": true, "readOnly": true } }, "required": [ "id", "created_at", "updated_at", "number", "subject", "customer_id", "first_response_at", "resolved_at", "closed_at", "sla_breached", "message_count" ] }, "TicketInput": { "type": "object", "properties": { "subject": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ], "nullable": true, "example": "open" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "nullable": true, "example": "low" }, "category": { "type": "string", "enum": [ "billing", "account", "bug", "feature", "howto" ], "nullable": true, "example": "billing" }, "channel": { "type": "string", "enum": [ "email", "chat", "phone", "web", "api" ], "nullable": true, "example": "email" }, "customer_id": { "type": "integer", "description": "The id of a customer." }, "requester_email": { "type": "string", "nullable": true }, "assignee_id": { "type": "integer", "nullable": true, "description": "The id of a agent." }, "team_id": { "type": "integer", "nullable": true, "description": "The id of a team." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Shape: string[]" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "satisfaction": { "type": "integer", "nullable": true, "description": "CSAT given at close.", "minimum": 1, "maximum": 5 } }, "required": [ "subject", "customer_id" ], "example": { "subject": "A subject", "status": "open", "priority": "low", "category": "billing", "channel": "email", "customer_id": 1 } }, "TicketList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Message": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "ticket_id": { "type": "integer", "description": "The id of a ticket." }, "author_type": { "type": "string", "enum": [ "customer", "agent", "system" ], "example": "customer" }, "author_id": { "type": "integer", "nullable": true, "description": "The agent, when author_type is agent. The id of a agent." }, "author_name": { "type": "string", "nullable": true }, "body": { "type": "string" }, "internal": { "type": "boolean", "nullable": true, "description": "A private note the customer does not see." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Shape: { name, size, content_type }[]" } }, "required": [ "id", "created_at", "updated_at", "ticket_id", "author_type", "body" ] }, "MessageInput": { "type": "object", "properties": { "ticket_id": { "type": "integer", "description": "The id of a ticket." }, "author_type": { "type": "string", "enum": [ "customer", "agent", "system" ], "example": "customer" }, "author_id": { "type": "integer", "nullable": true, "description": "The agent, when author_type is agent. The id of a agent." }, "author_name": { "type": "string", "nullable": true }, "body": { "type": "string" }, "internal": { "type": "boolean", "nullable": true, "description": "A private note the customer does not see." }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Shape: { name, size, content_type }[]" } }, "required": [ "ticket_id", "author_type", "body" ], "example": { "ticket_id": 1, "author_type": "customer", "body": "A body" } }, "MessageList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }