{ "openapi": "3.1.0", "info": { "title": "ClearWatch API", "version": "1", "description": "Read devices and issues, act on issues, and manage the webhooks ClearWatch sends issue events to.\n\nAuthenticate with an API key made under Settings, API keys: `Authorization: Bearer cwk_...`. A key belongs to an organization and reaches it and every organization below it that ClearWatch covers. It holds only the scopes it was given.\n\nWebhooks: each delivery is a POST of one event envelope (schema `Event`), signed with the endpoint's secret in the `ClearWatch-Signature` header as `t=,v1=`, where the hex is HMAC-SHA256 over `.`. Reject a timestamp more than 300 seconds from your clock. During a secret rotation a second `v1=` signed with the previous secret is present for 24 hours; accept either. Answer 2xx to accept. Anything else is retried with backoff for 24 hours. Delivery is at least once and not in order: drop duplicates by event `id` and order by `sequence`." }, "servers": [ { "url": "https://api.clearwatch.com/v1" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A ClearWatch API key (cwk_...)." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "conflict", "server_error" ] }, "message": { "type": "string" } } } } }, "Scope": { "type": "string", "enum": [ "watch:devices:read", "watch:issues:read", "watch:issues:write", "watch:issues:resolve", "watch:webhooks:read", "watch:webhooks:write", "watch:custom-fields:read", "watch:custom-fields:write", "watch:ipam:read", "watch:ipam:write" ], "description": "`watch:devices:read`: Organizations, locations and devices, with their status and last check-in.\n`watch:issues:read`: Open and closed issues (Alerts and Needs attention) and their timelines.\n`watch:issues:write`: Acknowledge an issue, take an acknowledgment back, and add a note to its timeline.\n`watch:issues:resolve`: Close an open issue with a reason. ClearPath keys only, as in the console.\n`watch:webhooks:read`: Webhook endpoints and their delivery logs. Never a signing secret.\n`watch:webhooks:write`: Create, change, test and delete webhook endpoints.\n`watch:custom-fields:read`: Custom field definitions, and the values that apply to devices, locations and organizations. A secret reads as set or not set, never its value.\n`watch:custom-fields:write`: Set, change, clear and lock custom field values on devices, locations and organizations, secrets included (write only).\n`watch:ipam:read`: Tracked subnets and blocks, the addresses in a subnet with their status, reservations, VLANs and the next free address.\n`watch:ipam:write`: Create and remove IPAM reservations, for a provisioning tool that takes the next free address." }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "organization": { "$ref": "#/components/schemas/Named" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "reaches_every_client": { "type": "boolean" } } }, "Named": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] } } }, "Location": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "parent_location_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] } } }, "Device": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "$ref": "#/components/schemas/Named" }, "location": { "oneOf": [ { "$ref": "#/components/schemas/Named" }, { "type": "null" } ] }, "name": { "type": "string" }, "hostname": { "type": "string" }, "kind": { "type": "string", "description": "`agent` or `bridge` (watched by a ClearBridge, no agent)." }, "device_type": { "type": [ "string", "null" ] }, "os": { "type": [ "string", "null" ] }, "os_version": { "type": [ "string", "null" ] }, "agent_version": { "type": [ "string", "null" ] }, "manufacturer": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "serial_number": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "enrolled_at": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } }, "Issue": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "$ref": "#/components/schemas/Named" }, "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label_when_opened": { "type": "string" } } }, "subject": { "type": "string" }, "source": { "type": "string" }, "outcome": { "type": "string", "enum": [ "alert", "attention" ], "description": "`alert` is on the Alerts list; `attention` is Needs attention." }, "state": { "type": "string", "description": "`warning` or `critical`, now." }, "worst_state": { "type": "string", "description": "The worst state reached while open." }, "headline": { "type": "string" }, "detail": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "opened_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "close_reason": { "type": [ "string", "null" ] }, "closed_by": { "type": [ "string", "null" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_by": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "TimelineEntry": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "detail": { "type": "string" }, "actor": { "type": [ "string", "null" ] } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "$ref": "#/components/schemas/Named" }, "name": { "type": "string" }, "url": { "type": "string" }, "enabled": { "type": "boolean" }, "subscribe": { "type": "boolean", "description": "Sent every event of event_types, not only what policy steps send it." }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "issue.opened", "issue.updated", "issue.acknowledged", "issue.unacknowledged", "issue.resolved", "issue.note_added" ] } }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "rotating_secret": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } }, "WebhookInput": { "type": "object", "properties": { "organization_id": { "type": "string", "description": "On create only. Defaults to the key's own organization." }, "name": { "type": "string" }, "url": { "type": "string", "description": "HTTPS, on a public address." }, "subscribe": { "type": "boolean" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "issue.opened", "issue.updated", "issue.acknowledged", "issue.unacknowledged", "issue.resolved", "issue.note_added" ] } }, "enabled": { "type": "boolean", "description": "On update only." } } }, "Event": { "type": "object", "description": "`issue.opened`: An issue opened\n`issue.updated`: An issue got worse or better while open\n`issue.acknowledged`: Somebody said they are on it\n`issue.unacknowledged`: An acknowledgment was taken back\n`issue.resolved`: An issue closed (recovered, or resolved by hand)\n`issue.note_added`: A note was added\n`issue.routed`: A policy step sent the issue here\n`ping`: A test from the Send test button", "required": [ "id", "type", "version", "sequence", "occurred_at", "organization", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "issue.opened", "issue.updated", "issue.acknowledged", "issue.unacknowledged", "issue.resolved", "issue.note_added", "issue.routed", "ping" ] }, "version": { "type": "integer", "const": 1 }, "sequence": { "type": "integer" }, "occurred_at": { "type": "string", "format": "date-time" }, "organization": { "oneOf": [ { "$ref": "#/components/schemas/Named" }, { "type": "null" } ] }, "data": { "type": "object", "properties": { "issue": { "type": [ "object", "null" ] }, "device": { "type": [ "object", "null" ] }, "change": { "type": "object", "properties": { "kind": { "type": "string" }, "detail": { "type": "string" }, "actor": { "type": [ "string", "null" ] } } } } } } } } }, "paths": { "/key": { "get": { "summary": "Which key this is, what it may do, and whose it is", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations": { "get": { "summary": "Organizations in reach", "description": "Needs the `watch:devices:read` scope.", "x-scope": "watch:devices:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/locations": { "get": { "summary": "Locations in reach", "description": "Needs the `watch:devices:read` scope.", "x-scope": "watch:devices:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one organization and those below it." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices": { "get": { "summary": "Managed devices, most recently seen first", "description": "Needs the `watch:devices:read` scope.", "x-scope": "watch:devices:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one organization and those below it." }, { "name": "location_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one location. Needs organization_id." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}": { "get": { "summary": "One device", "description": "Needs the `watch:devices:read` scope.", "x-scope": "watch:devices:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues": { "get": { "summary": "Issues, newest opened first", "description": "Needs the `watch:issues:read` scope.", "x-scope": "watch:issues:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "open" } }, { "name": "outcome", "in": "query", "schema": { "type": "string", "enum": [ "alert", "attention" ] } }, { "name": "device_id", "in": "query", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one organization and those below it." }, { "name": "location_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one location. Needs organization_id." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}": { "get": { "summary": "One issue", "description": "Needs the `watch:issues:read` scope.", "x-scope": "watch:issues:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}/events": { "get": { "summary": "An issue's timeline, oldest first", "description": "Needs the `watch:issues:read` scope.", "x-scope": "watch:issues:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEntry" } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}/acknowledge": { "post": { "summary": "Acknowledge an issue; stops escalation", "description": "Needs the `watch:issues:write` scope.", "x-scope": "watch:issues:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The issue is not in a state this applies to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}/unacknowledge": { "post": { "summary": "Take an acknowledgment back", "description": "Needs the `watch:issues:write` scope.", "x-scope": "watch:issues:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The issue is not in a state this applies to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}/notes": { "post": { "summary": "Add a note to an issue's timeline", "description": "Needs the `watch:issues:write` scope.", "x-scope": "watch:issues:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Added" }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/issues/{id}/resolve": { "post": { "summary": "Resolve an open issue by hand (ClearPath keys only)", "description": "Needs the `watch:issues:resolve` scope.", "x-scope": "watch:issues:resolve", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The issue is not in a state this applies to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "summary": "Webhooks in reach", "description": "Needs the `watch:webhooks:read` scope.", "x-scope": "watch:webhooks:read", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Make a webhook; the response carries its secret, once", "description": "Needs the `watch:webhooks:write` scope.", "x-scope": "watch:webhooks:write", "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "get": { "summary": "One webhook", "description": "Needs the `watch:webhooks:read` scope.", "x-scope": "watch:webhooks:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change a webhook; a field left out keeps its value", "description": "Needs the `watch:webhooks:write` scope.", "x-scope": "watch:webhooks:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a webhook and its log", "description": "Needs the `watch:webhooks:write` scope.", "x-scope": "watch:webhooks:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "summary": "Send a ping now and report the answer", "description": "Needs the `watch:webhooks:write` scope.", "x-scope": "watch:webhooks:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "A new signing secret, returned once", "description": "Needs the `watch:webhooks:write` scope.", "x-scope": "watch:webhooks:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "summary": "Recent deliveries and attempts", "description": "Needs the `watch:webhooks:read` scope.", "x-scope": "watch:webhooks:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/subnets": { "get": { "summary": "Tracked IPAM subnets and blocks in reach, with utilization and the next free address", "description": "Needs the `watch:ipam:read` scope.", "x-scope": "watch:ipam:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one organization and those below it." }, { "name": "location_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one location. Needs organization_id." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "location_id": { "type": [ "string", "null" ] }, "location_name": { "type": [ "string", "null" ] }, "cidr": { "type": "string" }, "kind": { "type": "string", "enum": [ "subnet", "block" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "vlan": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "tag": { "type": "integer" }, "name": { "type": "string" } } }, "gateway": { "type": [ "string", "null" ] }, "dns_servers": { "type": "array", "items": { "type": "string" } }, "expected_dhcp_servers": { "type": "array", "items": { "type": "string" } }, "use_for_filing": { "type": "boolean" }, "public": { "type": "boolean" }, "utilization": { "type": [ "object", "null" ], "properties": { "usable": { "type": "integer" }, "in_use": { "type": "integer" }, "stale": { "type": "integer" }, "reserved": { "type": "integer" }, "free": { "type": "integer" }, "percent_used": { "type": "number" } } }, "utilisation": { "type": [ "object", "null" ], "properties": { "usable": { "type": "integer" }, "in_use": { "type": "integer" }, "stale": { "type": "integer" }, "reserved": { "type": "integer" }, "free": { "type": "integer" }, "percent_used": { "type": "number" } }, "deprecated": true, "description": "The same object as utilization, under the name it shipped with. Deprecated: read utilization." }, "conflicts": { "type": "integer" }, "next_free": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/subnets/{id}/addresses": { "get": { "summary": "Every address seen in one subnet, with its status and every source that saw it", "description": "Needs the `watch:ipam:read` scope.", "x-scope": "watch:ipam:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "status": { "type": "string", "enum": [ "reserved", "in_use", "stale", "free" ] }, "hostname": { "type": [ "string", "null" ] }, "macs": { "type": "array", "items": { "type": "string" } }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "seen_by": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "mac": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "device_ids": { "type": "array", "items": { "type": "string" } }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "detail": { "type": "string" } } } } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/reservations": { "get": { "summary": "One subnet's reservations", "description": "Needs the `watch:ipam:read` scope.", "x-scope": "watch:ipam:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "subnet_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subnet_id": { "type": "string" }, "organization_id": { "type": "string" }, "first_ip": { "type": "string" }, "last_ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dhcp_pool", "excluded", "reserved" ] }, "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "mac": { "type": [ "string", "null" ] }, "device_id": { "type": [ "string", "null" ] }, "permanent": { "type": "boolean" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Reserve an address or a range inside a subnet", "description": "Needs the `watch:ipam:write` scope.", "x-scope": "watch:ipam:write", "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subnet_id", "first_ip" ], "properties": { "subnet_id": { "type": "string" }, "first_ip": { "type": "string" }, "last_ip": { "type": "string", "description": "For a range. Omit for one address." }, "kind": { "type": "string", "enum": [ "static", "dhcp_pool", "excluded", "reserved" ], "default": "static" }, "label": { "type": "string" }, "description": { "type": "string" }, "mac": { "type": "string" }, "device_id": { "type": "string" }, "permanent": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "subnet_id": { "type": "string" }, "organization_id": { "type": "string" }, "first_ip": { "type": "string" }, "last_ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dhcp_pool", "excluded", "reserved" ] }, "label": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "mac": { "type": [ "string", "null" ] }, "device_id": { "type": [ "string", "null" ] }, "permanent": { "type": "boolean" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/reservations/{id}": { "delete": { "summary": "Remove a reservation", "description": "Needs the `watch:ipam:write` scope.", "x-scope": "watch:ipam:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/vlans": { "get": { "summary": "Tracked VLANs in reach", "description": "Needs the `watch:ipam:read` scope.", "x-scope": "watch:ipam:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one organization and those below it." }, { "name": "location_id", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one location. Needs organization_id." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "The `next_cursor` of the previous page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "organization_name": { "type": "string" }, "location_id": { "type": [ "string", "null" ] }, "location_name": { "type": [ "string", "null" ] }, "tag": { "type": "integer", "minimum": 1, "maximum": 4094 }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "manual", "omada", "unifi", "meraki" ] } } } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ipam/next-free": { "get": { "summary": "The first free address in a subnet; does not reserve it", "description": "Needs the `watch:ipam:read` scope.", "x-scope": "watch:ipam:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "subnet_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subnet_id": { "type": "string" }, "cidr": { "type": "string" }, "address": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/custom-fields": { "get": { "summary": "Custom field definitions in reach", "description": "Needs the `watch:custom-fields:read` scope.", "x-scope": "watch:custom-fields:read", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "description": "Scripts read it as CW_ and set it with a CW_SET =value line." }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "yesno", "choice", "secret" ] }, "target": { "type": "string", "enum": [ "device", "place", "ipam_subnet", "ipam_address" ] }, "options": { "type": "array", "items": { "type": "string" } }, "device_types": { "type": "array", "items": { "type": "string" }, "description": "Empty is every type." }, "os_families": { "type": "array", "items": { "type": "string" }, "description": "Empty is any OS." }, "description": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "internal": { "type": "boolean" }, "validation": { "type": "object" }, "default_value": { "type": [ "string", "null" ] }, "default_set": { "type": "boolean" }, "default_locked": { "type": "boolean" }, "script_read": { "type": "boolean" }, "script_write": { "type": "boolean" }, "organization_id": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}/custom-fields": { "get": { "summary": "The custom field values that apply to a device, inherited or set there", "description": "Needs the `watch:custom-fields:read` scope.", "x-scope": "watch:custom-fields:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Set, clear or lock custom field values on a device; a field left out keeps its value", "description": "Needs the `watch:custom-fields:write` scope.", "x-scope": "watch:custom-fields:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Field key (or id) to value. Null or an empty string clears it here." }, "locks": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Field key (or id) to whether the value binds everything below. Organizations and locations only." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "400": { "description": "A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/custom-fields": { "get": { "summary": "The custom field values that apply to an organization, inherited or set there", "description": "Needs the `watch:custom-fields:read` scope.", "x-scope": "watch:custom-fields:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Set, clear or lock custom field values on an organization; a field left out keeps its value", "description": "Needs the `watch:custom-fields:write` scope.", "x-scope": "watch:custom-fields:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Field key (or id) to value. Null or an empty string clears it here." }, "locks": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Field key (or id) to whether the value binds everything below. Organizations and locations only." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "400": { "description": "A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/locations/{id}/custom-fields": { "get": { "summary": "The custom field values that apply to a location, inherited or set there", "description": "Needs the `watch:custom-fields:read` scope.", "x-scope": "watch:custom-fields:read", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Set, clear or lock custom field values on a location; a field left out keeps its value", "description": "Needs the `watch:custom-fields:write` scope.", "x-scope": "watch:custom-fields:write", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Field key (or id) to value. Null or an empty string clears it here." }, "locks": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Field key (or id) to whether the value binds everything below. Organizations and locations only." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applies": { "type": "boolean" }, "set": { "type": "boolean" }, "value": { "type": [ "string", "null" ], "description": "Always null for a secret." }, "source": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "locked_by": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "default", "organization", "location", "device" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "own": { "type": [ "object", "null" ], "properties": { "value": { "type": [ "string", "null" ] }, "locked": { "type": "boolean" } } } } } } } } } } }, "400": { "description": "A value that does not parse, a field that does not apply or is locked above, or a key that is not a field here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is unknown, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key does not have the scope this needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or not in this key's reach (one answer for both).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 requests this minute for this key. See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }