{ "openapi": "3.1.0", "info": { "title": "Kanishu ITAM 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://itam.kanishu.com/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/api-access-requests": { "post": { "operationId": "postApiAccessRequestsStore", "summary": "Create in api access requests", "tags": [ "Api" ], "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": {} } } } } }, "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" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_ips": { "type": "string", "nullable": true, "maxLength": 2000 }, "api_client_id": { "type": "integer", "nullable": true }, "purpose": { "type": "string", "maxLength": 1000 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "people:read", "people:write", "assets:read", "assets:write", "licenses:read", "licenses:write", "reports:read", "cis:read", "assets:audit-read", "vendors:notify", "discovery:report" ] }, "minItems": 1 }, "validity_days": { "type": "integer", "nullable": true, "enum": [ "30", "60", "90" ] } }, "required": [ "purpose", "scopes" ] } } } } } }, "/api-access-requests/pending": { "get": { "operationId": "getApiAccessRequestsPendingPending", "summary": "Pending (api access requests pending)", "tags": [ "Api" ], "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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" } } } }, "/api-access-requests/{apiAccessRequest}/approve": { "post": { "operationId": "postApiAccessRequestsApproveApprove", "summary": "Approve (api access requests approve)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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" } } } }, "/api-access-requests/{apiAccessRequest}/reject": { "post": { "operationId": "postApiAccessRequestsRejectReject", "summary": "Reject (api access requests reject)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [ "reason" ] } } } } } }, "/api-access-requests/{apiAccessRequest}/reveal": { "get": { "operationId": "getApiAccessRequestsRevealReveal", "summary": "Reveal (api access requests reveal)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "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": { "token": { "type": "string", "description": "The API token, shown this once. Store it in your secrets manager and send it as Authorization: Bearer ." } } } } } }, "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" } } } }, "/assets": { "get": { "operationId": "getAssetsIndex", "summary": "List assets", "tags": [ "Assets" ], "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": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[category]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[department]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[vendor]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[external_vendor_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "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: `licenses` — The software licences allocated to the asset, as GET /licenses returns them (needs `licenses:read`)." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "sub_category": { "type": [ "string", "null" ], "description": "Finer category within it." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "The person the asset is assigned to (id, name, email), or null." }, "department": { "type": "string" }, "location": { "type": "string" }, "warranty_end_date": { "type": "string", "format": "date" }, "purchase_cost": { "type": "string", "description": "Purchase price in the asset's currency." }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "processor": { "type": [ "string", "null" ] }, "ram": { "type": [ "string", "null" ], "description": "Memory, as recorded (e.g. 16 GB)." }, "storage": { "type": [ "string", "null" ], "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "operating_system": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "purchase_date": { "type": "string", "format": "date" }, "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "warranty_status": { "type": "string", "description": "active or expired, from warranty_end_date; null when no warranty date is recorded." }, "amc_status": { "type": [ "string", "null" ], "description": "active or expired, from the maintenance contract (AMC) end date; null when none." }, "service_record_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "most_recent_service_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Repairs and services recorded for the asset: count and the most recent service date." }, "license_count": { "type": "integer", "description": "How many software licences are allocated to the asset (?include=licenses lists them)." }, "licenses": { "type": "array", "items": {}, "description": "Only with ?include=licenses. The software licences allocated to the asset, as GET /licenses returns them." } } }, "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" }, "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 `assets:read` scope.", "x-scope": "assets:read" }, "post": { "operationId": "postAssetsStore", "summary": "Create in assets", "tags": [ "Assets" ], "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": "integer" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "sub_category": { "type": [ "string", "null" ], "description": "Finer category within it." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "The person the asset is assigned to (id, name, email), or null." }, "department": { "type": "string" }, "location": { "type": "string" }, "warranty_end_date": { "type": "string", "format": "date" }, "purchase_cost": { "type": "string", "description": "Purchase price in the asset's currency." }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "processor": { "type": [ "string", "null" ] }, "ram": { "type": [ "string", "null" ], "description": "Memory, as recorded (e.g. 16 GB)." }, "storage": { "type": [ "string", "null" ], "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "operating_system": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "purchase_date": { "type": "string", "format": "date" }, "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "warranty_status": { "type": "string", "description": "active or expired, from warranty_end_date; null when no warranty date is recorded." }, "amc_status": { "type": [ "string", "null" ], "description": "active or expired, from the maintenance contract (AMC) end date; null when none." }, "service_record_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "most_recent_service_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Repairs and services recorded for the asset: count and the most recent service date." }, "license_count": { "type": "integer", "description": "How many software licences are allocated to the asset (?include=licenses lists them)." } } } } } } } }, "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 `assets:write` scope.", "x-scope": "assets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amc_cost": { "type": "number", "nullable": true, "minimum": 0 }, "amc_end_date": { "type": "string", "nullable": true, "format": "date" }, "amc_provider": { "type": "string", "nullable": true, "maxLength": 255, "description": "Who provides the annual maintenance contract (AMC)." }, "amc_start_date": { "type": "string", "nullable": true, "format": "date" }, "asset_tag": { "type": "string", "maxLength": 100, "description": "Your organisation's tag for the asset (unique)." }, "category_id": { "type": "integer" }, "currency": { "type": "string", "nullable": true }, "current_book_value": { "type": "number", "nullable": true, "minimum": 0, "description": "Value after depreciation (audit feed)." }, "custom_fields_json": { "type": "string", "nullable": true, "description": "Your organisation's own extra fields, by field name." }, "department_id": { "type": "integer", "nullable": true }, "depreciation_method": { "type": "string", "nullable": true, "maxLength": 100, "description": "How the book value is worked out over the asset's life." }, "expected_useful_life_years": { "type": "integer", "nullable": true, "minimum": 0, "description": "Years over which the asset is depreciated." }, "funding_source": { "type": "string", "nullable": true, "maxLength": 255, "description": "Which budget paid for it (e.g. capex, a project)." }, "fx_rate_override": { "type": "number", "nullable": true, "minimum": 0, "description": "An exchange rate to use instead of the day's reference rate (1 unit of currency in home currency)." }, "hostname": { "type": "string", "nullable": true, "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "maxLength": 100 }, "location_id": { "type": "integer", "nullable": true }, "mac_address": { "type": "string", "nullable": true, "maxLength": 100 }, "manufacturer": { "type": "string", "nullable": true, "maxLength": 255 }, "model_number": { "type": "string", "nullable": true, "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "operating_system": { "type": "string", "nullable": true, "maxLength": 100 }, "os_version": { "type": "string", "nullable": true, "maxLength": 100 }, "payment_terms": { "type": "string", "nullable": true, "maxLength": 255 }, "processor": { "type": "string", "nullable": true, "maxLength": 255 }, "purchase_cost": { "type": "number", "nullable": true, "minimum": 0, "description": "Purchase price in the asset's currency." }, "purchase_date": { "type": "string", "nullable": true, "format": "date" }, "purchase_order_number": { "type": "string", "nullable": true, "maxLength": 100 }, "ram": { "type": "string", "nullable": true, "maxLength": 100, "description": "Memory, as recorded (e.g. 16 GB)." }, "screen_size": { "type": "string", "nullable": true, "maxLength": 50 }, "serial_number": { "type": "string", "nullable": true, "maxLength": 255 }, "storage": { "type": "string", "nullable": true, "maxLength": 100, "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "sub_category": { "type": "string", "nullable": true, "maxLength": 100, "description": "Finer category within it." }, "vendor_id": { "type": "integer", "nullable": true, "description": "The supplier, from Vendor management (if you use it); vendor_name otherwise." }, "vendor_name": { "type": "string", "nullable": true, "maxLength": 255 }, "warranty_end_date": { "type": "string", "nullable": true, "format": "date" }, "warranty_start_date": { "type": "string", "nullable": true, "format": "date" } }, "required": [ "asset_tag", "category_id", "name" ] } } } } } }, "/assets/audit-feed": { "get": { "operationId": "getAssetsAuditFeedAuditFeed", "summary": "Audit Feed (assets audit feed)", "tags": [ "Assets" ], "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" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "current_book_value": { "type": [ "string", "null" ], "description": "Value after depreciation (audit feed)." }, "expected_useful_life_years": { "type": [ "integer", "null" ], "description": "Years over which the asset is depreciated." }, "purchase_date": { "type": [ "string", "null" ], "format": "date" }, "disposal_date": { "type": [ "string", "null" ], "format": "date" }, "data_wipe_confirmed": { "type": "boolean", "description": "true when wiping the data was confirmed before disposal." }, "destruction_certificate_reference": { "type": [ "string", "null" ], "description": "Reference of the certificate of destruction, for disposed assets." }, "serial_number": { "type": [ "string", "null" ] }, "hostname": { "type": [ "string", "null" ] }, "purchase_cost": { "type": [ "string", "null" ], "description": "Purchase price in the asset's currency." }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When network discovery last saw the device." }, "last_audit_scan_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the asset was last scanned in a physical audit." }, "assignment_date": { "type": [ "string", "null" ], "format": "date" }, "assignee_name": { "type": [ "string", "null" ] }, "assignee_email": { "type": [ "string", "null" ] }, "assignee_person_uuid": { "type": [ "string", "null" ], "format": "uuid", "description": "The assigned person's People id." } } }, "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 `assets:audit-read` scope.", "x-scope": "assets:audit-read" } }, "/assets/{asset}": { "get": { "operationId": "getAssetsShow", "summary": "Get one of assets", "tags": [ "Assets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "asset", "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." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `licenses` — The software licences allocated to the asset, as GET /licenses returns them (needs `licenses:read`)." } ], "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": "integer" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "sub_category": { "type": [ "string", "null" ], "description": "Finer category within it." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "The person the asset is assigned to (id, name, email), or null." }, "department": { "type": "string" }, "location": { "type": "string" }, "warranty_end_date": { "type": "string", "format": "date" }, "purchase_cost": { "type": "string", "description": "Purchase price in the asset's currency." }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "processor": { "type": [ "string", "null" ] }, "ram": { "type": [ "string", "null" ], "description": "Memory, as recorded (e.g. 16 GB)." }, "storage": { "type": [ "string", "null" ], "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "operating_system": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "purchase_date": { "type": "string", "format": "date" }, "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "warranty_status": { "type": "string", "description": "active or expired, from warranty_end_date; null when no warranty date is recorded." }, "amc_status": { "type": [ "string", "null" ], "description": "active or expired, from the maintenance contract (AMC) end date; null when none." }, "service_record_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "most_recent_service_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Repairs and services recorded for the asset: count and the most recent service date." }, "license_count": { "type": "integer", "description": "How many software licences are allocated to the asset (?include=licenses lists them)." }, "licenses": { "type": "array", "items": {}, "description": "Only with ?include=licenses. The software licences allocated to the asset, as GET /licenses returns them." } } } } } } } }, "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 `assets:read` scope.", "x-scope": "assets:read" }, "patch": { "operationId": "patchAssetsUpdate", "summary": "Change one of assets", "tags": [ "Assets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "asset", "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": "integer" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "sub_category": { "type": [ "string", "null" ], "description": "Finer category within it." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "The person the asset is assigned to (id, name, email), or null." }, "department": { "type": "string" }, "location": { "type": "string" }, "warranty_end_date": { "type": "string", "format": "date" }, "purchase_cost": { "type": "string", "description": "Purchase price in the asset's currency." }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "processor": { "type": [ "string", "null" ] }, "ram": { "type": [ "string", "null" ], "description": "Memory, as recorded (e.g. 16 GB)." }, "storage": { "type": [ "string", "null" ], "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "operating_system": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "purchase_date": { "type": "string", "format": "date" }, "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "warranty_status": { "type": "string", "description": "active or expired, from warranty_end_date; null when no warranty date is recorded." }, "amc_status": { "type": [ "string", "null" ], "description": "active or expired, from the maintenance contract (AMC) end date; null when none." }, "service_record_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "most_recent_service_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Repairs and services recorded for the asset: count and the most recent service date." }, "license_count": { "type": "integer", "description": "How many software licences are allocated to the asset (?include=licenses lists them)." } } } } } } } }, "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 `assets:write` scope.", "x-scope": "assets:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amc_cost": { "type": "number", "nullable": true, "minimum": 0 }, "amc_end_date": { "type": "string", "nullable": true, "format": "date" }, "amc_provider": { "type": "string", "nullable": true, "maxLength": 255, "description": "Who provides the annual maintenance contract (AMC)." }, "amc_start_date": { "type": "string", "nullable": true, "format": "date" }, "category_id": { "type": "integer" }, "currency": { "type": "string", "nullable": true }, "current_book_value": { "type": "number", "nullable": true, "minimum": 0, "description": "Value after depreciation (audit feed)." }, "custom_fields_json": { "type": "string", "nullable": true, "description": "Your organisation's own extra fields, by field name." }, "department_id": { "type": "integer", "nullable": true }, "deployment_notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "depreciation_method": { "type": "string", "nullable": true, "maxLength": 100, "description": "How the book value is worked out over the asset's life." }, "enrolled_in_mdm_at": { "type": "string", "nullable": true, "format": "date", "description": "When the device was enrolled in mobile device management." }, "expected_useful_life_years": { "type": "integer", "nullable": true, "minimum": 0, "description": "Years over which the asset is depreciated." }, "funding_source": { "type": "string", "nullable": true, "maxLength": 255, "description": "Which budget paid for it (e.g. capex, a project)." }, "fx_rate_override": { "type": "number", "nullable": true, "minimum": 0, "description": "An exchange rate to use instead of the day's reference rate (1 unit of currency in home currency)." }, "hostname": { "type": "string", "nullable": true, "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "maxLength": 100 }, "location_id": { "type": "integer", "nullable": true }, "mac_address": { "type": "string", "nullable": true, "maxLength": 100 }, "manufacturer": { "type": "string", "nullable": true, "maxLength": 255 }, "model_number": { "type": "string", "nullable": true, "maxLength": 255 }, "name": { "type": "string", "maxLength": 255 }, "operating_system": { "type": "string", "nullable": true, "maxLength": 100 }, "os_imaged_at": { "type": "string", "nullable": true, "format": "date", "description": "When the operating system image was installed." }, "os_version": { "type": "string", "nullable": true, "maxLength": 100 }, "payment_terms": { "type": "string", "nullable": true, "maxLength": 255 }, "processor": { "type": "string", "nullable": true, "maxLength": 255 }, "purchase_cost": { "type": "number", "nullable": true, "minimum": 0, "description": "Purchase price in the asset's currency." }, "purchase_date": { "type": "string", "nullable": true, "format": "date" }, "purchase_order_number": { "type": "string", "nullable": true, "maxLength": 100 }, "ram": { "type": "string", "nullable": true, "maxLength": 100, "description": "Memory, as recorded (e.g. 16 GB)." }, "screen_size": { "type": "string", "nullable": true, "maxLength": 50 }, "security_agent_installed_at": { "type": "string", "nullable": true, "format": "date", "description": "When the security agent was installed." }, "serial_number": { "type": "string", "nullable": true, "maxLength": 255 }, "storage": { "type": "string", "nullable": true, "maxLength": 100, "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "sub_category": { "type": "string", "nullable": true, "maxLength": 100, "description": "Finer category within it." }, "vendor_id": { "type": "integer", "nullable": true, "description": "The supplier, from Vendor management (if you use it); vendor_name otherwise." }, "vendor_name": { "type": "string", "nullable": true, "maxLength": 255 }, "warranty_end_date": { "type": "string", "nullable": true, "format": "date" }, "warranty_start_date": { "type": "string", "nullable": true, "format": "date" } } } } } } }, "delete": { "operationId": "deleteAssetsDestroy", "summary": "Delete one of assets", "tags": [ "Assets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "412": { "$ref": "#/components/responses/E412" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `assets:write` scope.", "x-scope": "assets:write" } }, "/assets/{asset}/reclaim": { "post": { "operationId": "postAssetsReclaimReclaim", "summary": "Reclaim (assets reclaim)", "tags": [ "Assets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "asset", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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": "integer" }, "asset_tag": { "type": "string", "description": "Your organisation's tag for the asset (unique)." }, "name": { "type": "string" }, "category": { "type": "string", "description": "Asset category (e.g. Laptop, Server)." }, "sub_category": { "type": [ "string", "null" ], "description": "Finer category within it." }, "status": { "type": "string", "description": "in_stock, assigned, in_repair, retired or disposed." }, "assigned_to": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "description": "The person the asset is assigned to (id, name, email), or null." }, "department": { "type": "string" }, "location": { "type": "string" }, "warranty_end_date": { "type": "string", "format": "date" }, "purchase_cost": { "type": "string", "description": "Purchase price in the asset's currency." }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "processor": { "type": [ "string", "null" ] }, "ram": { "type": [ "string", "null" ], "description": "Memory, as recorded (e.g. 16 GB)." }, "storage": { "type": [ "string", "null" ], "description": "Disk storage, as recorded (e.g. 512 GB SSD)." }, "operating_system": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "purchase_date": { "type": "string", "format": "date" }, "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "warranty_status": { "type": "string", "description": "active or expired, from warranty_end_date; null when no warranty date is recorded." }, "amc_status": { "type": [ "string", "null" ], "description": "active or expired, from the maintenance contract (AMC) end date; null when none." }, "service_record_summary": { "type": "object", "properties": { "count": { "type": "integer" }, "most_recent_service_date": { "type": [ "string", "null" ], "format": "date" } }, "description": "Repairs and services recorded for the asset: count and the most recent service date." }, "license_count": { "type": "integer", "description": "How many software licences are allocated to the asset (?include=licenses lists them)." } } } } } } } }, "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 `assets:write` scope.", "x-scope": "assets:write" } }, "/assets/{asset}/same-model": { "get": { "operationId": "getAssetsSameModelSameModel", "summary": "Same Model (assets same model)", "tags": [ "Assets" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "asset", "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": { "manufacturer": { "type": "string" }, "model_number": { "type": "string" }, "asset_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ids of assets of the same make and model." } } } } } } } }, "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 `assets:read` scope.", "x-scope": "assets:read" } }, "/configuration-items": { "get": { "operationId": "getConfigurationItemsIndex", "summary": "List configuration items", "tags": [ "Configuration" ], "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": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[asset_id]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[ids]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[ci_class]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[environment]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[criticality]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated; prefix - for descending. Allowed: name, created_at, updated_at. Default: name." }, { "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": "integer" }, "name": { "type": "string" }, "class": { "type": "string", "description": "What kind of item: application, server, database, network, endpoint, cloud_resource, storage_backup, identity_certificate, external_service, software_license or other." }, "lifecycle_state": { "type": "string", "description": "planned, in_build, live, retiring or retired." }, "operational_status": { "type": "string", "description": "operational, degraded, down, maintenance or unknown." }, "environment": { "type": [ "string", "null" ], "description": "production, test, development or disaster_recovery." }, "criticality": { "type": [ "string", "null" ], "description": "Business criticality: critical, high, medium or low." }, "asset": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "asset_tag": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "description": "The asset behind the item, if any." }, "license_id": { "type": [ "integer", "null" ], "description": "The licence behind the item, if it is a software licence." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string", "description": "The relationship in words, as read in that direction." }, "direction": { "type": "string", "description": "outgoing (this item → target) or incoming (target → this item)." }, "target_ci_id": { "type": "integer", "description": "The other item's id." }, "target": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "asset_tag": { "type": [ "string", "null" ] } } } } }, "description": "How the item connects to others (depends on, runs on, …)." }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "criticality": { "type": "string" } } }, "description": "The business services that rely on the item." } } }, "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 `cis:read` scope.", "x-scope": "cis:read" } }, "/configuration-items/{configurationItem}": { "get": { "operationId": "getConfigurationItemsShow", "summary": "Get one of configuration items", "tags": [ "Configuration" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "configurationItem", "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": "integer" }, "name": { "type": "string" }, "class": { "type": "string", "description": "What kind of item: application, server, database, network, endpoint, cloud_resource, storage_backup, identity_certificate, external_service, software_license or other." }, "lifecycle_state": { "type": "string", "description": "planned, in_build, live, retiring or retired." }, "operational_status": { "type": "string", "description": "operational, degraded, down, maintenance or unknown." }, "environment": { "type": [ "string", "null" ], "description": "production, test, development or disaster_recovery." }, "criticality": { "type": [ "string", "null" ], "description": "Business criticality: critical, high, medium or low." }, "asset": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "asset_tag": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "description": "The asset behind the item, if any." }, "license_id": { "type": [ "integer", "null" ], "description": "The licence behind the item, if it is a software licence." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string", "description": "The relationship in words, as read in that direction." }, "direction": { "type": "string", "description": "outgoing (this item → target) or incoming (target → this item)." }, "target_ci_id": { "type": "integer", "description": "The other item's id." }, "target": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "asset_tag": { "type": [ "string", "null" ] } } } } }, "description": "How the item connects to others (depends on, runs on, …)." }, "services": { "type": "array", "items": {}, "description": "The business services that rely on the item." } } } } } } } }, "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 `cis:read` scope.", "x-scope": "cis:read" } }, "/discovery/config": { "get": { "operationId": "getDiscoveryConfigConfig", "summary": "Config (discovery config)", "tags": [ "Discovery" ], "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": { "name": { "type": "string", "description": "The collector's name." }, "subnets": { "type": "array", "items": { "type": "string" }, "description": "Network ranges the collector should scan." }, "scan_frequency_hours": { "type": "integer", "description": "How often to scan." }, "credentials": { "type": "string", "description": "Always stored_on_collector: scan credentials stay on your collector and are never sent to Kanishu." }, "settings": { "type": "object", "properties": { "max_addresses": { "type": "integer" }, "tcp_ports": { "type": "array" }, "ping_timeout_ms": { "type": "integer" }, "snmp_timeout_ms": { "type": "integer" }, "cim_timeout_sec": { "type": "integer" }, "batch_size": { "type": "integer" } }, "description": "Scan limits and timeouts the collector should use (addresses, ports, timeouts, batch size)." } } } } } } } }, "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 `discovery:report` scope.", "x-scope": "discovery:report" } }, "/discovery/scans": { "post": { "operationId": "postDiscoveryScansSubmitScan", "summary": "Submit Scan (discovery scans)", "tags": [ "Discovery" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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 `discovery:report` scope.", "x-scope": "discovery:report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "object", "properties": { "bios_uuid": { "type": "string", "nullable": true, "maxLength": 64 }, "discovery_methods": { "type": "array", "items": {}, "nullable": true, "description": "How the device was found (e.g. ping, snmp, wmi)." }, "hostname": { "type": "string", "nullable": true, "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "maxLength": 45 }, "mac_address": { "type": "string", "nullable": true, "maxLength": 64 }, "probe_status": { "type": "array", "items": {}, "nullable": true, "description": "How far the probe got for this device." }, "serial_number": { "type": "string", "nullable": true, "maxLength": 255 }, "snmp_data": { "type": "array", "items": {}, "nullable": true }, "vendor": { "type": "string", "nullable": true, "maxLength": 255 }, "wmi_data": { "type": "array", "items": {}, "nullable": true } } }, "maxItems": 1000 }, "scan": { "type": "object", "properties": { "batch": { "type": "integer", "minimum": 1, "maximum": 10000 }, "final": { "type": "boolean", "description": "true on the last batch of a scan." }, "id": { "type": "string", "maxLength": 64 }, "started_at": { "type": "string", "nullable": true, "format": "date" }, "summary": { "type": "object", "properties": { "addresses_alive": { "type": "integer", "nullable": true, "minimum": 0 }, "addresses_scanned": { "type": "integer", "nullable": true, "minimum": 0 }, "errors": { "type": "array", "items": {}, "nullable": true, "maxItems": 500 } }, "nullable": true }, "version": { "type": "string", "nullable": true, "maxLength": 20 } }, "nullable": true } } } } } } } }, "/licenses": { "get": { "operationId": "getLicensesIndex", "summary": "List licenses", "tags": [ "Licenses" ], "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": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text." }, { "name": "filter[vendor]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "name": "filter[license_type]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only records with this value; several values comma-separated mean \"any of\"." }, { "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: `assets` — The assets the licence is allocated to, as GET /assets returns them (needs `assets:read`)." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "vendor": { "type": "string", "description": "The software publisher or reseller." }, "license_type": { "type": "string", "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "seats_purchased": { "type": "integer", "description": "Seats bought." }, "seats_allocated": { "type": "integer", "description": "Seats allocated to assets." }, "seats_available": { "type": "integer", "description": "Seats still free (purchased minus allocated)." }, "compliance_status": { "type": "string", "description": "compliant, over_allocated (more in use than bought) or under_utilized (many seats unused)." }, "start_date": { "type": "string", "format": "date" }, "expiry_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "assets": { "type": "array", "items": {}, "description": "Only with ?include=assets. The assets the licence is allocated to, as GET /assets returns them." } } }, "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 `licenses:read` scope.", "x-scope": "licenses:read" }, "post": { "operationId": "postLicensesStore", "summary": "Create in licenses", "tags": [ "Licenses" ], "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": "integer" }, "name": { "type": "string" }, "vendor": { "type": "string", "description": "The software publisher or reseller." }, "license_type": { "type": "string", "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "seats_purchased": { "type": "integer", "description": "Seats bought." }, "seats_allocated": { "type": "integer", "description": "Seats allocated to assets." }, "seats_available": { "type": "integer", "description": "Seats still free (purchased minus allocated)." }, "compliance_status": { "type": "string", "description": "compliant, over_allocated (more in use than bought) or under_utilized (many seats unused)." }, "start_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date" }, "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 `licenses:write` scope.", "x-scope": "licenses:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "nullable": true }, "department_id": { "type": "integer", "nullable": true }, "expiry_date": { "type": "string", "nullable": true, "format": "date" }, "fx_rate_override": { "type": "number", "nullable": true, "minimum": 0 }, "license_key_encrypted": { "type": "string", "nullable": true, "maxLength": 2000, "description": "The licence key; stored encrypted and never shown in full again." }, "license_type": { "type": "string", "enum": [ "perpetual", "subscription_monthly", "subscription_annual", "per_seat", "per_device", "concurrent_user", "site" ], "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "location_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "maxLength": 255 }, "seats_purchased": { "type": "integer", "minimum": 1, "description": "Seats bought." }, "start_date": { "type": "string", "format": "date" }, "support_contract_reference": { "type": "string", "nullable": true, "maxLength": 255, "description": "Reference of the support or maintenance contract." }, "total_cost": { "type": "number", "nullable": true, "minimum": 0 }, "unit_cost": { "type": "number", "nullable": true, "minimum": 0 }, "vendor": { "type": "string", "maxLength": 255, "description": "The software publisher or reseller." }, "version": { "type": "string", "nullable": true, "maxLength": 255 } }, "required": [ "license_type", "name", "seats_purchased", "start_date", "vendor" ] } } } } } }, "/licenses-compliance-report": { "get": { "operationId": "getLicensesComplianceReportComplianceReport", "summary": "Compliance Report (licenses compliance report)", "tags": [ "Licenses" ], "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "over_allocated": { "type": "array", "items": {}, "description": "Licences with more seats in use than bought." }, "expiring_soon": { "type": "array", "items": {}, "description": "Licences whose expiry date is near." } } } } } }, "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 `reports:read` scope.", "x-scope": "reports:read" } }, "/licenses/{license}": { "get": { "operationId": "getLicensesShow", "summary": "Get one of licenses", "tags": [ "Licenses" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "license", "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." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `assets` — The assets the licence is allocated to, as GET /assets returns them (needs `assets:read`)." } ], "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": "integer" }, "name": { "type": "string" }, "vendor": { "type": "string", "description": "The software publisher or reseller." }, "license_type": { "type": "string", "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "seats_purchased": { "type": "integer", "description": "Seats bought." }, "seats_allocated": { "type": "integer", "description": "Seats allocated to assets." }, "seats_available": { "type": "integer", "description": "Seats still free (purchased minus allocated)." }, "compliance_status": { "type": "string", "description": "compliant, over_allocated (more in use than bought) or under_utilized (many seats unused)." }, "start_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "assets": { "type": "array", "items": {}, "description": "Only with ?include=assets. The assets the licence is allocated to, as GET /assets returns them." } } } } } } } }, "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 `licenses:read` scope.", "x-scope": "licenses:read" } }, "/licenses/{license}/allocations": { "post": { "operationId": "postLicensesAllocationsAllocateSeat", "summary": "Allocate Seat (licenses allocations)", "tags": [ "Licenses" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "license", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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": "integer" }, "name": { "type": "string" }, "vendor": { "type": "string", "description": "The software publisher or reseller." }, "license_type": { "type": "string", "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "seats_purchased": { "type": "integer", "description": "Seats bought." }, "seats_allocated": { "type": "integer", "description": "Seats allocated to assets." }, "seats_available": { "type": "integer", "description": "Seats still free (purchased minus allocated)." }, "compliance_status": { "type": "string", "description": "compliant, over_allocated (more in use than bought) or under_utilized (many seats unused)." }, "start_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date" }, "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 `licenses:write` scope.", "x-scope": "licenses:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_over_allocation": { "type": "boolean", "description": "true to allocate even when no seats are free (the licence then shows as over_allocated)." }, "asset_id": { "type": "integer", "description": "The asset to allocate the seat to, or take it back from." } }, "required": [ "asset_id" ] } } } } } }, "/licenses/{license}/reclaim-seat": { "post": { "operationId": "postLicensesReclaimSeatReclaimSeat", "summary": "Reclaim Seat (licenses reclaim seat)", "tags": [ "Licenses" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "license", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "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": "integer" }, "name": { "type": "string" }, "vendor": { "type": "string", "description": "The software publisher or reseller." }, "license_type": { "type": "string", "description": "perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site." }, "seats_purchased": { "type": "integer", "description": "Seats bought." }, "seats_allocated": { "type": "integer", "description": "Seats allocated to assets." }, "seats_available": { "type": "integer", "description": "Seats still free (purchased minus allocated)." }, "compliance_status": { "type": "string", "description": "compliant, over_allocated (more in use than bought) or under_utilized (many seats unused)." }, "start_date": { "type": "string", "format": "date" }, "expiry_date": { "type": "string", "format": "date" }, "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 `licenses:write` scope.", "x-scope": "licenses:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "integer", "description": "The asset to allocate the seat to, or take it back from." } }, "required": [ "asset_id" ] } } } } } }, "/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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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/assets": { "get": { "operationId": "getPeopleAssetsIndex", "summary": "List people assets", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 255 }, "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." } ], "responses": { "200": { "description": "Every matching record in one answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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 `assets:read` scope.", "x-scope": "assets: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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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/reclaim": { "post": { "operationId": "postPeopleReclaimReclaim", "summary": "Reclaim (people reclaim)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {}, "meta": { "type": "object", "properties": { "reclaimed": {} } } } } } } }, "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 `assets:reclaim` scope. Used between Kanishu products; not offered to customers.", "x-scope": "assets:reclaim", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "release_licenses": { "type": "boolean" } }, "required": [ "email" ] } } } } } }, "/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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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", "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", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "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" ] } } } } } }, "/vendors/directory-changed": { "post": { "operationId": "postVendorsDirectoryChangedChanged", "summary": "Changed (vendors directory changed)", "tags": [ "Vendors" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "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 `vendors:notify` scope.", "x-scope": "vendors:notify" } } }, "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" } } } } } } }