{ "openapi": "3.1.0", "info": { "title": "Kanishu ITSM API", "version": "v1", "description": "Generated from the product's routes (suite/api-kit). Conventions — lists, values, versions, retries, limits — are in the Kanishu API standard; every error uses the envelope below, with the codes in \"API errors\"." }, "servers": [ { "url": "https://itsm.kanishu.com/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/changes/audit-feed": { "get": { "operationId": "getChangesAuditFeedAuditFeed", "summary": "Audit Feed (changes audit feed)", "tags": [ "Changes" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 2000 }, "description": "Answer in pages of this many records (10–2000). Without it, everything comes back at once." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The `meta.next_after` from the previous page (start with 0)." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "Records in id order. With page_size, `meta.next_after` is the `after` for the next page (null on the last).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "standard_change": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "version": { "type": "integer" }, "linked_by_name": { "type": [ "string", "null" ] }, "linked_at": { "type": [ "string", "null" ], "format": "date-time" }, "in_scope": { "type": [ "boolean", "null" ], "description": "Whether the person linking confirmed the change fits the standard's scope." }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "approved_before_link": { "type": "boolean", "description": "true when the standard was approved before this change was linked to it." }, "self_approved": { "type": "boolean", "description": "true when the standard's approver also wrote or submitted it." }, "status_now": { "type": [ "string", "null" ] }, "review_due_on": { "type": [ "string", "null" ], "format": "date" }, "failures": { "type": "integer", "description": "How many changes under this standard have failed." } }, "description": "The approved standard change it follows, if any." }, "id": { "type": "integer" }, "subject": { "type": "string" }, "change_type": { "type": "string", "description": "standard (pre-approved), normal or emergency." }, "risk": { "type": "string", "description": "Assessed risk: low, medium or high." }, "status": { "type": "string" }, "implementation_plan": { "type": "string", "description": "How the change will be carried out." }, "rollback_plan": { "type": [ "string", "null" ], "description": "How it will be undone if it fails." }, "outcome": { "type": [ "string", "null" ], "description": "How it went once done: successful, failed or partial (null until then)." }, "created_by_user_id": { "type": "integer" }, "created_by_name": { "type": "string" }, "approved_by_user_id": { "type": [ "integer", "null" ], "description": "Who approved it." }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "type": "array" }, "meta": { "type": "object", "properties": { "next_after": { "type": [ "integer", "null" ] } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `changes:audit-read` scope.", "x-scope": "changes:audit-read" } }, "/component-tickets": { "post": { "operationId": "postComponentTicketsStoreForComponent", "summary": "Store For Component (component tickets)", "tags": [ "Component" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:write` scope.", "x-scope": "tickets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "organization_id": { "type": "integer", "description": "Your organisation's id." }, "priority": { "type": "string", "nullable": true, "enum": [ "low", "medium", "high", "urgent" ] }, "related_component_display_name": { "type": "string", "maxLength": 255, "description": "A readable name for it (e.g. the asset tag)." }, "related_component_id": { "type": "integer", "description": "That record's id in the other product." }, "related_component_type": { "type": "string", "enum": [ "asset", "license", "vendor" ], "description": "What the ticket is about in the other product (e.g. asset, license)." }, "reporter_email": { "type": "string", "format": "email", "maxLength": 255 }, "reporter_name": { "type": "string", "maxLength": 255 }, "subject": { "type": "string", "maxLength": 255 } }, "required": [ "description", "organization_id", "related_component_display_name", "related_component_id", "related_component_type", "reporter_email", "reporter_name", "subject" ] } } } } } }, "/knowledge": { "get": { "operationId": "getKnowledgeIndex", "summary": "List knowledge", "tags": [ "Knowledge" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "Every matching record in one answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "excerpt": { "type": "string", "description": "The start of the article, for lists and search results." }, "category": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Where the article is in Ticketing." } } }, "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `knowledge:read` scope.", "x-scope": "knowledge:read" } }, "/knowledge/{id}": { "get": { "operationId": "getKnowledgeShow", "summary": "Get one of knowledge", "tags": [ "Knowledge" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string", "description": "The full article." }, "category": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `knowledge:read` scope.", "x-scope": "knowledge:read" } }, "/people": { "get": { "operationId": "getPeopleIndex", "summary": "List people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" }, "post": { "operationId": "postPeopleStore", "summary": "Create in people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name" ] } } } } } }, "/people-organisation": { "get": { "operationId": "getPeopleOrganisationOrganisation", "summary": "Organisation (people organisation)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "description": "What kind of unit it is (e.g. department, team, business unit)." }, "code": { "type": "string" }, "part_of_id": { "type": [ "integer", "string", "null" ], "description": "The unit this one sits under, or null at the top." }, "in_use": { "type": "boolean", "description": "false when the unit is archived and no longer offered." } } } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the position is archived." } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the location is archived." } } } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" } }, "/people/joiners": { "post": { "operationId": "postPeopleJoinersJoin", "summary": "Add a joiner (from their start date)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The new person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "nullable": true, "description": "Logins they should get, as product key => role (e.g. {\"itsm\": \"agent\"}); each one waits for an approval." }, "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "start_date": { "type": "string", "format": "date", "description": "Their first working day; their logins are prepared for it." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name", "start_date" ] } } } } } }, "/people/{person}": { "get": { "operationId": "getPeopleShow", "summary": "Get one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope.", "x-scope": "people:read" }, "patch": { "operationId": "patchPeopleUpdate", "summary": "Change one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } } } } } } } }, "/people/{person}/leave": { "post": { "operationId": "postPeopleLeaveLeave", "summary": "Record a leaver (logins switched off after the last working day, or now if urgent)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "last_working_date": { "type": "string", "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "reason": { "type": "string", "nullable": true, "maxLength": 500, "description": "Why they are leaving (kept in People's History)." }, "urgent": { "type": "boolean", "description": "true to switch their logins off now instead of after the last working day." } }, "required": [ "last_working_date" ] } } } } } }, "/people/{person}/move": { "post": { "operationId": "postPeopleMoveMove", "summary": "Move a person (department, manager, position or location) from a date", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope.", "x-scope": "people:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "department_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team they move to, from GET /people-organisation." }, "effective_date": { "type": "string", "format": "date", "description": "The date the move takes effect." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Their new manager's People id." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "effective_date" ] } } } } } }, "/tickets": { "get": { "operationId": "getTicketsIndex", "summary": "List tickets", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "related_component_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "related_component_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "requester_domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "requester_emails", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `comments` — The ticket's public comments (internal notes are never included): author_name, body, created_at — as on GET /tickets/{id} (needs `comments:read`); `fulfillment_tasks` — The request's fulfilment tasks: id, name, status, requires_approval — as GET /tickets/{id}/fulfillment-tasks returns them (needs `tickets:read`); `relationships` — Linked tickets: label, ticket_id, subject, status — as GET /tickets/{id}/relationships returns them (needs `tickets:read`)." } ], "responses": { "200": { "description": "Every matching record in one answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "status": { "type": "string", "description": "open, in_progress, pending, blocked, resolved, closed, not_applicable or cancelled." }, "priority": { "type": "string", "description": "low, medium, high or urgent." }, "category": { "type": [ "string", "null" ], "description": "The ticket's category name." }, "assigned_to": { "type": [ "string", "null" ], "description": "Name of the agent working on it, or null." }, "created_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "description": "Where the ticket is in Ticketing (add it to https://itsm.kanishu.com)." }, "comments": { "type": "array", "items": {}, "description": "Only with ?include=comments. The ticket's public comments (internal notes are never included): author_name, body, created_at — as on GET /tickets/{id}." }, "fulfillment_tasks": { "type": "array", "items": {}, "description": "Only with ?include=fulfillment_tasks. The request's fulfilment tasks: id, name, status, requires_approval — as GET /tickets/{id}/fulfillment-tasks returns them." }, "relationships": { "type": "array", "items": {}, "description": "Only with ?include=relationships. Linked tickets: label, ticket_id, subject, status — as GET /tickets/{id}/relationships returns them." } } }, "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:read` scope.", "x-scope": "tickets:read" }, "post": { "operationId": "postTicketsStore", "summary": "Create in tickets", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "description": "Where the ticket is in Ticketing (add it to https://itsm.kanishu.com)." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:write` scope.", "x-scope": "tickets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category_id": { "type": "integer", "nullable": true, "description": "A ticket category id; leave out to let your routing rules decide." }, "description": { "type": "string" }, "priority": { "type": "string", "nullable": true, "enum": [ "low", "medium", "high", "urgent" ], "description": "low, medium, high or urgent." }, "subject": { "type": "string", "maxLength": 255 } }, "required": [ "description", "subject" ] } } } } } }, "/tickets/audit-feed": { "get": { "operationId": "getTicketsAuditFeedAuditFeed", "summary": "Audit Feed (tickets audit feed)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 10, "maximum": 2000 }, "description": "Answer in pages of this many records (10–2000). Without it, everything comes back at once." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The `meta.next_after` from the previous page (start with 0)." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "Records in id order. With page_size, `meta.next_after` is the `after` for the next page (null on the last).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "status": { "type": "string", "description": "open, in_progress, pending, blocked, resolved, closed, not_applicable or cancelled." }, "priority": { "type": "string", "description": "low, medium, high or urgent." }, "category": { "type": [ "string", "null" ], "description": "The ticket's category name." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "problem_id": { "type": [ "integer", "null" ], "description": "The problem record the incident is linked to, if any (audit feed)." }, "problem_root_cause": { "type": [ "string", "null" ], "description": "The linked problem's root cause, if recorded (audit feed)." } } }, "type": "array" }, "meta": { "type": "object", "properties": { "next_after": { "type": [ "integer", "null" ] } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:audit-read` scope.", "x-scope": "tickets:audit-read" } }, "/tickets/{id}": { "get": { "operationId": "getTicketsShow", "summary": "Get one of tickets", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "description": "open, in_progress, pending, blocked, resolved, closed, not_applicable or cancelled." }, "priority": { "type": "string", "description": "low, medium, high or urgent." }, "category": { "type": [ "string", "null" ], "description": "The ticket's category name." }, "assigned_to": { "type": [ "string", "null" ], "description": "Name of the agent working on it, or null." }, "requester_name": { "type": "string", "description": "Who raised it." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "comments": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:read` scope.", "x-scope": "tickets:read" } }, "/tickets/{id}/comments": { "post": { "operationId": "postTicketsCommentsStoreComment", "summary": "Store Comment (tickets comments)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:write` scope.", "x-scope": "tickets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "author_name": { "type": "string", "maxLength": 255, "description": "Name to show as the comment's author." }, "body": { "type": "string" } }, "required": [ "author_name", "body" ] } } } } } }, "/tickets/{id}/csat": { "post": { "operationId": "postTicketsCsatSubmitCsat", "summary": "Submit Csat (tickets csat)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:write` scope.", "x-scope": "tickets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csat_comment": { "type": "string", "nullable": true, "maxLength": 2000 }, "csat_rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Satisfaction rating from 1 (poor) to 5 (excellent)." } }, "required": [ "csat_rating" ] } } } } } }, "/tickets/{id}/fulfillment-tasks": { "get": { "operationId": "getTicketsFulfillmentTasksFulfillmentTasks", "summary": "Fulfillment Tasks (tickets fulfillment tasks)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": {}, "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:read` scope.", "x-scope": "tickets:read" } }, "/tickets/{id}/fulfillment-tasks/{taskId}/complete": { "post": { "operationId": "postTicketsFulfillmentTasksCompleteCompleteFulfillmentTask", "summary": "Complete Fulfillment Task (tickets fulfillment tasks complete)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "description": "open, in_progress, pending, blocked, resolved, closed, not_applicable or cancelled." } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:write` scope.", "x-scope": "tickets:write" } }, "/tickets/{id}/relationships": { "get": { "operationId": "getTicketsRelationshipsRelationships", "summary": "Relationships (tickets relationships)", "tags": [ "Tickets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": {}, "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `tickets:read` scope.", "x-scope": "tickets:read" } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A token from API Access in the product. Never put it in a URL." } }, "parameters": { "RequestId": { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,64}$" }, "description": "Your id for this call; echoed back. Generated when absent." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{8,100}$" }, "description": "Makes a POST safe to retry: the first answer is kept for 24 hours." }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag you read. The change is refused with 412 version_conflict if the record changed since." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "invalid_token", "bad_signature", "token_in_url", "session_expired", "ip_not_allowed", "invalid_scope", "forbidden", "forbidden_organization", "not_supported", "feature_not_included", "subscription_read_only", "subscription_suspended", "limit_reached", "rate_limited", "quota_exceeded", "daily_limit_exceeded", "bad_request", "invalid_request", "request_failed", "validation_failed", "missing_organization_id", "not_eligible", "approval_refused", "incomplete", "activation_failed", "idempotency_key_reused", "idempotency_in_progress", "invalid_filter", "invalid_sort", "invalid_include", "invalid_fields", "not_found", "method_not_allowed", "conflict", "duplicate", "exists", "version_conflict", "payload_too_large", "unsupported_media_type", "product_maintenance", "product_disabled", "platform_tenant_not_configured", "unavailable", "server_error" ] }, "message": { "type": "string" }, "details": { "type": "object" }, "request_id": { "type": "string" } } } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } }, "responses": { "E400": { "description": "Bad request (invalid_filter, invalid_sort, invalid_fields, bad_request).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No or bad token (unauthenticated, invalid_token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Plan limit or feature (limit_reached, feature_not_included).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Not allowed (invalid_scope, forbidden, forbidden_organization, ip_not_allowed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (duplicate, idempotency_key_reused, idempotency_in_progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E412": { "description": "The record changed since you read it (version_conflict).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Validation failed; details.fields lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Too many calls (rate_limited, daily quota). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Server error. Quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Unavailable (maintenance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }