{ "openapi": "3.1.0", "info": { "title": "Cadence Ops Agent API", "version": "1.1.0", "description": "Scoped, audited REST surface for AI agents (Hermes, Agentzero A0, GPTs, Claude). Bearer token auth; every call is RLS-enforced and workspace-scoped. Available on the Enterprise plan." }, "servers": [ { "url": "https://cadenceops.app" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Mint a token in Settings → Agent API." } } }, "security": [ { "bearerAuth": [] } ], "x-scopes": { "events:read": "Read events", "events:write": "Create / update events", "milestones:read": "Read milestones", "milestones:write": "Create / update / complete milestones", "movements:read": "Read logistics movements", "movements:write": "Create / update logistics movements", "equipment:read": "Read equipment list", "equipment:write": "Log damage & maintenance", "chat:read": "Read channels the owner is in", "chat:write": "Post notes to channels", "pins:read": "Read site map pins", "pins:write": "Update site map pins", "email:send": "Send emails from info@cadenceops.app", "email:read": "Read mailbox threads & messages" }, "paths": { "/api/public/agent/v1/me": { "get": { "summary": "Identify the token (owner, scopes, write flag)", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ownerId": { "type": "string", "format": "uuid" }, "canWrite": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "ownerId", "canWrite", "scopes" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/openapi.json": { "get": { "summary": "Machine-readable OpenAPI manifest (paste URL into a0.dev / GPT / Claude)", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/events": { "get": { "summary": "List events (filters: status, from, to)", "security": [ { "bearerAuth": [ "events:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "from", "in": "query", "required": false, "description": "ISO date — events on or after", "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } }, { "name": "to", "in": "query", "required": false, "description": "ISO date — events on or before", "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "client": { "type": "string", "nullable": true }, "venue": { "type": "string", "nullable": true }, "event_date": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "crew_size": { "type": "integer", "nullable": true }, "value": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "client", "venue", "event_date", "status", "crew_size", "value", "notes", "updated_at" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } }, "post": { "summary": "Create an event", "security": [ { "bearerAuth": [ "events:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "client": { "type": "string", "nullable": true }, "venue": { "type": "string", "nullable": true }, "event_date": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "crew_size": { "type": "integer", "nullable": true }, "value": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "client", "venue", "event_date", "status", "crew_size", "value", "notes", "updated_at" ], "additionalProperties": false } }, "required": [ "event" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "client": { "type": "string", "maxLength": 200 }, "venue": { "type": "string", "maxLength": 200 }, "event_date": { "type": "string", "description": "ISO 8601 date or datetime" }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "crew_size": { "type": "integer", "minimum": 0, "maximum": 10000 }, "notes": { "type": "string", "maxLength": 4000 } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/events/{id}": { "get": { "summary": "Event detail + milestones", "security": [ { "bearerAuth": [ "events:read", "milestones:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "client": { "type": "string", "nullable": true }, "venue": { "type": "string", "nullable": true }, "event_date": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "crew_size": { "type": "integer", "nullable": true }, "value": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "client", "venue", "event_date", "status", "crew_size", "value", "notes", "updated_at" ], "additionalProperties": false }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } } }, "required": [ "event", "milestones" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } }, "patch": { "summary": "Update event status / notes / crew_size", "security": [ { "bearerAuth": [ "events:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "client": { "type": "string", "nullable": true }, "venue": { "type": "string", "nullable": true }, "event_date": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "crew_size": { "type": "integer", "nullable": true }, "value": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "client", "venue", "event_date", "status", "crew_size", "value", "notes", "updated_at" ], "additionalProperties": false } }, "required": [ "event" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "notes": { "type": "string", "maxLength": 4000, "nullable": true }, "crew_size": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false } } } } } }, "/api/public/agent/v1/events/{id}/milestones": { "get": { "summary": "List milestones for an event", "security": [ { "bearerAuth": [ "milestones:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } } }, "required": [ "milestones" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } }, "post": { "summary": "Create a milestone", "security": [ { "bearerAuth": [ "milestones:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } }, "required": [ "milestone" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "scheduled_at": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "maxLength": 2000 }, "position": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "label" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/milestones": { "get": { "summary": "List milestones across the workspace (filters: event_id, status, from, to)", "security": [ { "bearerAuth": [ "milestones:read" ] } ], "parameters": [ { "name": "event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "format": "uuid" } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } } }, "required": [ "milestones" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/milestones/{id}": { "patch": { "summary": "Update a milestone", "security": [ { "bearerAuth": [ "milestones:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } }, "required": [ "milestone" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "pending", "in_progress", "complete" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "maxLength": 2000, "nullable": true }, "position": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "additionalProperties": false } } } } } }, "/api/public/agent/v1/milestones/{id}/complete": { "post": { "summary": "Mark a milestone complete", "security": [ { "bearerAuth": [ "milestones:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "milestone": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "position": { "type": "integer" }, "notes": { "type": "string", "nullable": true } }, "required": [ "id", "label", "status", "scheduled_at", "completed_at", "position", "notes" ], "additionalProperties": false } }, "required": [ "milestone" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/movements": { "get": { "summary": "List logistics movements (filters: status, event)", "security": [ { "bearerAuth": [ "movements:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "event", "in": "query", "required": false, "description": "Substring match against event field", "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "movements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true }, "event": { "type": "string", "nullable": true }, "from_location": { "type": "string", "nullable": true }, "to_location": { "type": "string", "nullable": true }, "vehicle": { "type": "string", "nullable": true }, "depart_at": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "reference", "event", "from_location", "to_location", "vehicle", "depart_at", "status", "notes", "updated_at" ], "additionalProperties": false } } }, "required": [ "movements" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } }, "post": { "summary": "Create a logistics movement", "security": [ { "bearerAuth": [ "movements:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "movement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true }, "event": { "type": "string", "nullable": true }, "from_location": { "type": "string", "nullable": true }, "to_location": { "type": "string", "nullable": true }, "vehicle": { "type": "string", "nullable": true }, "depart_at": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "reference", "event", "from_location", "to_location", "vehicle", "depart_at", "status", "notes", "updated_at" ], "additionalProperties": false } }, "required": [ "movement" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "event": { "type": "string", "maxLength": 200 }, "from_location": { "type": "string", "maxLength": 200 }, "to_location": { "type": "string", "maxLength": 200 }, "vehicle": { "type": "string", "maxLength": 120 }, "depart_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "notes": { "type": "string", "maxLength": 4000 } }, "additionalProperties": false } } } } } }, "/api/public/agent/v1/movements/{id}": { "patch": { "summary": "Update movement status / depart / notes", "security": [ { "bearerAuth": [ "movements:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "movement": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "nullable": true }, "event": { "type": "string", "nullable": true }, "from_location": { "type": "string", "nullable": true }, "to_location": { "type": "string", "nullable": true }, "vehicle": { "type": "string", "nullable": true }, "depart_at": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "reference", "event", "from_location", "to_location", "vehicle", "depart_at", "status", "notes", "updated_at" ], "additionalProperties": false } }, "required": [ "movement" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1, "maxLength": 40 }, "depart_at": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "type": "string", "maxLength": 4000, "nullable": true } }, "additionalProperties": false } } } } } }, "/api/public/agent/v1/equipment": { "get": { "summary": "Search equipment (query param: q)", "security": [ { "bearerAuth": [ "equipment:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Substring match on name / asset_id", "schema": { "anyOf": [ { "not": {} }, { "type": "string", "maxLength": 100 } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "location", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "category_id", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "format": "uuid" } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "equipment": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "asset_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "category_id": { "type": "string", "nullable": true }, "brand": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "owner": { "type": "string", "nullable": true }, "replacement_value": { "type": "number", "nullable": true }, "hire_rate": { "type": "number", "nullable": true }, "next_service_due": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "asset_id", "name", "category_id", "brand", "model", "status", "location", "owner", "replacement_value", "hire_rate", "next_service_due", "updated_at" ], "additionalProperties": false } } }, "required": [ "equipment" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/equipment-damage": { "post": { "summary": "Log damage against an equipment item", "security": [ { "bearerAuth": [ "equipment:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "equipment_id": { "type": "string", "format": "uuid" }, "severity": { "type": "string", "enum": [ "minor", "major", "out_of_service" ] }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "equipment_id" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/equipment-maintenance": { "post": { "summary": "Schedule or log maintenance", "security": [ { "bearerAuth": [ "equipment:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "equipment_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "service", "inspection", "repair" ] }, "scheduled_for": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "equipment_id" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/chat": { "get": { "summary": "List recent chat messages (filters: channel_id, since, limit≤200)", "security": [ { "bearerAuth": [ "chat:read" ] } ], "parameters": [ { "name": "channel_id", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "format": "uuid" } ] } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "integer", "minimum": 1, "maximum": 200 } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "sender_id": { "type": "string", "format": "uuid", "nullable": true }, "body": { "type": "string" }, "priority": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "channel_id", "sender_id", "body", "priority", "created_at" ], "additionalProperties": false } } }, "required": [ "messages" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/channels": { "get": { "summary": "List chat channels the owner can post to", "security": [ { "bearerAuth": [ "chat:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/notes": { "post": { "summary": "Post a note to a chat channel as the token owner", "security": [ { "bearerAuth": [ "chat:write" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "channel_id", "body" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/pins": { "get": { "summary": "List site map pins across the workspace (filters: site_map_id, status, kind, department)", "security": [ { "bearerAuth": [ "pins:read" ] } ], "parameters": [ { "name": "site_map_id", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "format": "uuid" } ] } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "department", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_map_id": { "type": "string", "format": "uuid", "nullable": true }, "kind": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "x": { "type": "number" }, "y": { "type": "number" }, "last_task": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "site_map_id", "kind", "label", "role", "department", "status", "x", "y", "last_task", "notes", "updated_at" ], "additionalProperties": false } } }, "required": [ "pins" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/site-maps/{id}/pins": { "get": { "summary": "List pins on a single site map", "security": [ { "bearerAuth": [ "pins:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_map_id": { "type": "string", "format": "uuid", "nullable": true }, "kind": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "x": { "type": "number" }, "y": { "type": "number" }, "last_task": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "site_map_id", "kind", "label", "role", "department", "status", "x", "y", "last_task", "notes", "updated_at" ], "additionalProperties": false } } }, "required": [ "pins" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/pins/{id}": { "patch": { "summary": "Update pin (status / x,y / last_task / notes)", "security": [ { "bearerAuth": [ "pins:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pin": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "site_map_id": { "type": "string", "format": "uuid", "nullable": true }, "kind": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "x": { "type": "number" }, "y": { "type": "number" }, "last_task": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "updated_at": { "type": "string" } }, "required": [ "id", "site_map_id", "kind", "label", "role", "department", "status", "x", "y", "last_task", "notes", "updated_at" ], "additionalProperties": false } }, "required": [ "pin" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "busy", "alert" ] }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "last_task": { "type": "string", "maxLength": 500, "nullable": true }, "notes": { "type": "string", "maxLength": 2000, "nullable": true } }, "additionalProperties": false } } } } } }, "/api/public/agent/v1/email/send": { "post": { "summary": "Send an email from info@cadenceops.app (to ≤5 recipients per call, ≤110 sends per token per day)", "security": [ { "bearerAuth": [ "email:send" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "messageIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "suppressed": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "queued", "messageIds", "suppressed" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 5 } ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "replyTo": { "type": "string", "format": "email" } }, "required": [ "to", "subject", "body" ], "additionalProperties": false } } } } } }, "/api/public/agent/v1/email/threads": { "get": { "summary": "List email threads (filters: status, q, since, limit)", "security": [ { "bearerAuth": [ "email:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "q", "in": "query", "required": false, "description": "Substring match on subject", "schema": { "anyOf": [ { "not": {} }, { "type": "string" } ] } }, { "name": "since", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "string", "description": "ISO 8601 date or datetime" } ], "description": "ISO 8601 date or datetime" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "integer", "minimum": 1, "maximum": 200 } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "nullable": true }, "participants": { "type": "array", "items": { "type": "string" }, "nullable": true }, "status": { "type": "string", "nullable": true }, "unread_count": { "type": "integer", "nullable": true }, "last_message_at": { "type": "string", "nullable": true }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "id", "subject", "participants", "status", "unread_count", "last_message_at", "assigned_to" ], "additionalProperties": false } } }, "required": [ "threads" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/email/threads/{id}": { "get": { "summary": "Thread detail + messages + signed attachment URLs (URLs expire in 5 minutes)", "security": [ { "bearerAuth": [ "email:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } }, "/api/public/agent/v1/email/search": { "get": { "summary": "Full-text-ish search across subject + body (q required, min 2 chars)", "security": [ { "bearerAuth": [ "email:read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "not": {} }, { "type": "integer", "minimum": 1, "maximum": 100 } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "direction": { "type": "string" }, "from_address": { "type": "string" }, "subject": { "type": "string", "nullable": true }, "body_text": { "type": "string", "nullable": true }, "received_at": { "type": "string" } }, "required": [ "id", "thread_id", "direction", "from_address", "subject", "body_text", "received_at" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "400": { "description": "Validation error (invalid body or query)" }, "401": { "description": "Missing or invalid bearer token" }, "403": { "description": "Token missing required scope or not on Enterprise plan" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit or per-token quota exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } } } } } } } }