openapi: 3.1.0 info: title: Legion Platform API version: 3.19.0 servers: - url: https://api.hopper.west.prod.govcloud.legion.picogrid.com description: US Government Production API - url: https://legion-prod.picogrid.com description: Commercial Production API paths: /v3/.well-known/oauth-authorization-server: get: summary: Get OAuth 2.0 Authorization Server Metadata description: Returns OAuth 2.0 authorization server metadata as defined in RFC 8414 by proxying to Keycloak's well-known endpoint tags: - Auth responses: "200": description: Successful response content: application/json: schema: example: authorization_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/auth code_challenge_methods_supported: - plain - S256 grant_types_supported: - authorization_code - refresh_token - client_credentials introspection_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/token/introspect issuer: https://auth.legion.com/realms/legion jwks_uri: https://auth.legion.com/realms/legion/protocol/openid-connect/certs response_types_supported: - code - id_token - token id_token revocation_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/revoke scopes_supported: - openid - profile - email - offline_access token_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/token properties: authorization_endpoint: example: https://auth.legion.com/realms/legion/protocol/openid-connect/auth type: string code_challenge_methods_supported: example: - plain - S256 items: type: string type: array device_authorization_endpoint: example: https://auth.legion.com/realms/legion/protocol/openid-connect/auth/device type: string grant_types_supported: example: - authorization_code - implicit - refresh_token - password - client_credentials - urn:ietf:params:oauth:grant-type:device_code items: type: string type: array introspection_endpoint: example: https://auth.legion.com/realms/legion/protocol/openid-connect/token/introspect type: string issuer: example: https://auth.legion.com/realms/legion type: string jwks_uri: example: https://auth.legion.com/realms/legion/protocol/openid-connect/certs type: string registration_endpoint: example: https://auth.legion.com/realms/legion/clients-registrations/openid-connect type: string request_parameter_supported: example: true type: boolean request_uri_parameter_supported: example: true type: boolean require_request_uri_registration: example: true type: boolean response_modes_supported: example: - query - fragment - form_post items: type: string type: array response_types_supported: example: - code - id_token - token id_token - code id_token - code token - code token id_token items: type: string type: array revocation_endpoint: example: https://auth.legion.com/realms/legion/protocol/openid-connect/revoke type: string scopes_supported: example: - openid - profile - email - offline_access items: type: string type: array token_endpoint: example: https://auth.legion.com/realms/legion/protocol/openid-connect/token type: string token_endpoint_auth_methods_supported: example: - client_secret_basic - client_secret_post - client_secret_jwt - private_key_jwt items: type: string type: array required: - issuer - authorization_endpoint - token_endpoint - jwks_uri - response_types_supported type: object example: authorization_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/auth code_challenge_methods_supported: - plain - S256 grant_types_supported: - authorization_code - refresh_token - client_credentials introspection_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/token/introspect issuer: https://auth.legion.com/realms/legion jwks_uri: https://auth.legion.com/realms/legion/protocol/openid-connect/certs response_types_supported: - code - id_token - token id_token revocation_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/revoke scopes_supported: - openid - profile - email - offline_access token_endpoint: https://auth.legion.com/realms/legion/protocol/openid-connect/token "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object "502": description: Bad Gateway content: application/json: schema: properties: category: type: string code: example: 500 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: External service integration failed type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/auth/providers/keycloak/register: post: summary: Register with Keycloak description: Registers a new user account using Keycloak authentication provider tags: - Auth requestBody: required: true content: application/json: schema: example: first_name: John id_token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJFRXB2UXpvSzVhczNlZVE2RVR1aW1QTkpnYzQyWEpmRVgwbDZEbHFzdUZnIn0... last_name: Doe properties: first_name: example: John type: string id_token: example: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJFRXB2UXpvSzVhczNlZVE2RVR1aW1QTkpnYzQyWEpmRVgwbDZEbHFzdUZnIn0... type: string last_name: example: Doe type: string required: - first_name - last_name - id_token type: object example: first_name: John id_token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJFRXB2UXpvSzVhczNlZVE2RVR1aW1QTkpnYzQyWEpmRVgwbDZEbHFzdUZnIn0... last_name: Doe responses: "201": description: Resource created successfully content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/audit: get: summary: Get permission audit trail description: Get the permission audit trail with optional filtering. Requires organization context. tags: - Authorization parameters: - name: action in: query required: false schema: example: grant type: string - name: end_date in: query required: false schema: example: "2024-02-16T21:45:33Z" type: string - name: limit in: query required: false schema: example: 50 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: example: 0 minimum: 0 type: integer - name: resource_id in: query required: false schema: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string - name: resource_type in: query required: false schema: example: entity type: string - name: start_date in: query required: false schema: example: "2024-01-16T21:45:33Z" type: string - name: subject_id in: query required: false schema: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string - name: subject_type in: query required: false schema: example: user type: string responses: "200": description: Successful response content: application/json: schema: example: entries: - {} total_count: 1 properties: entries: example: - {} items: example: action: grant id: 1 performed_at: "2024-02-16T21:45:33Z" performed_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 reason: Granting access for project collaboration relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: action: example: grant type: string id: example: 1 type: integer performed_at: example: "2024-02-16T21:45:33.123456789Z" type: string performed_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string reason: example: Granting access for project collaboration maxLength: 500 minLength: 1 type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - id - action type: object type: array total_count: example: 1 type: integer required: - entries - total_count type: object example: entries: - {} total_count: 1 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/check: post: summary: Check permission description: Check if a subject has a specific permission. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string type: object example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 responses: "200": description: Successful response content: application/json: schema: example: allowed: true from_cache: false reason: Direct permission granted properties: allowed: example: true type: boolean from_cache: example: false type: boolean reason: example: Direct permission granted type: string required: - allowed - from_cache type: object example: allowed: true from_cache: false reason: Direct permission granted "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/check-bulk: post: summary: Check multiple permissions description: Check multiple permissions in a single operation. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: checks: - {} properties: checks: example: - {} items: example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string type: object type: array required: - checks type: object example: checks: - {} responses: "200": description: Successful response content: application/json: schema: example: results: - {} total_count: 1 properties: results: example: - {} items: example: allowed: true from_cache: false index: 0 reason: Direct permission granted properties: allowed: example: true type: boolean from_cache: example: false type: boolean index: example: 0 type: integer reason: example: Direct permission granted type: string required: - index - allowed - reason - from_cache type: object type: array total_count: example: 1 type: integer required: - results - total_count type: object example: results: - {} total_count: 1 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/expand: post: summary: Expand permissions description: Find all subjects that have access to a resource. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: limit: 25 offset: 0 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: inheritance_source: enum: - direct - inherited - template example: direct type: string limit: example: 50 maximum: 100 minimum: 1 type: integer offset: example: 0 minimum: 0 type: integer relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject_type: example: user type: string type: object example: limit: 25 offset: 0 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 responses: "200": description: Successful response content: application/json: schema: example: direct_subjects: - {} organization_id: 123e4567-e89b-12d3-a456-426614174000 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 total_count: 1 properties: count: example: 10 type: integer direct_subjects: example: - {} items: example: granted_at: "2024-02-16T21:45:33Z" granted_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 relation: viewer source: direct subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: granted_at: example: "2024-02-16T21:45:33.123456789Z" type: string granted_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string relation: example: viewer type: string source: enum: - direct - inherited example: direct type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - source type: object type: array has_more: example: true type: boolean offset: example: 0 type: integer organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string total_count: example: 25 type: integer required: - direct_subjects - total_count - count - offset - has_more type: object example: direct_subjects: - {} organization_id: 123e4567-e89b-12d3-a456-426614174000 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 total_count: 1 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/grant: post: summary: Grant permissions description: Grant permissions to one or more subjects. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: grants: - {} properties: grants: example: - {} items: example: reason: Granting access for project collaboration relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: reason: example: Granting access for project collaboration maxLength: 500 minLength: 1 type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string type: object type: array required: - grants type: object example: grants: - {} responses: "201": description: Resource created successfully content: application/json: schema: example: affected_count: 1 message: Successfully granted 1 permissions success: true properties: affected_count: example: 1 type: integer message: example: Successfully granted 1 permissions type: string success: example: true type: boolean required: - success - message - affected_count type: object example: affected_count: 1 message: Successfully granted 1 permissions success: true "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/path: post: summary: Trace permission path description: Trace how a subject acquired a specific permission. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string type: object example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 responses: "200": description: Successful response content: application/json: schema: example: final_reason: Permission granted through direct assignment organization_id: 123e4567-e89b-12d3-a456-426614174000 path: - {} relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: final_reason: example: Permission granted through direct assignment type: string organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string path: example: - {} items: example: depth: 0 reason: Direct permission granted source_path: - org:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: depth: example: 0 type: integer reason: example: Direct permission granted type: string source_path: example: - org:123e4567-e89b-12d3-a456-426614174000 - team:456e7890-1234-5678-9abc-def012345678 items: type: string type: array subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - reason - depth type: object type: array relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - path - final_reason type: object example: final_reason: Permission granted through direct assignment organization_id: 123e4567-e89b-12d3-a456-426614174000 path: - {} relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/revoke: post: summary: Revoke permissions description: Revoke permissions from one or more subjects. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: revocations: - {} properties: revocations: example: - {} items: example: reason: Removing access due to role change relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: reason: example: Granting access for project collaboration maxLength: 500 minLength: 1 type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string type: object type: array required: - revocations type: object example: revocations: - {} responses: "200": description: Successful response content: application/json: schema: example: affected_count: 1 message: Successfully granted 1 permissions success: true properties: affected_count: example: 1 type: integer message: example: Successfully granted 1 permissions type: string success: example: true type: boolean required: - success - message - affected_count type: object example: affected_count: 1 message: Successfully granted 1 permissions success: true "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/subjects: post: summary: List subjects with permissions description: Find all subjects that have a specific permission on a resource. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: limit: 25 offset: 0 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: inheritance_source: enum: - direct - inherited - template example: direct type: string limit: example: 50 maximum: 100 minimum: 1 type: integer offset: example: 0 minimum: 0 type: integer relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subject_type: example: user type: string type: object example: limit: 25 offset: 0 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 responses: "200": description: Successful response content: application/json: schema: example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subjects: - {} total_count: 1 properties: count: example: 10 type: integer has_more: example: true type: boolean offset: example: 0 type: integer relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string subjects: example: - {} items: example: granted_at: "2024-02-16T21:45:33Z" granted_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 relation: viewer source: direct subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: granted_at: example: "2024-02-16T21:45:33.123456789Z" type: string granted_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string relation: example: viewer type: string source: enum: - direct - inherited example: direct type: string subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - source type: object type: array total_count: example: 25 type: integer required: - subjects - total_count - count - offset - has_more type: object example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 subjects: - {} total_count: 1 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/templates: get: summary: List permission templates description: List all permission templates for the organization. Requires organization context. tags: - Authorization parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: has_more: example: false type: boolean limit: example: 50 type: integer offset: example: 0 type: integer templates: example: - {} items: example: created_at: "2024-02-16T21:45:33Z" created_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Standard entity viewing permissions icon: entity-icon id: 123e4567-e89b-12d3-a456-426614174000 is_system: false name: Entity Viewer organization_id: 123e4567-e89b-12d3-a456-426614174000 permissions: entity: - {} updated_at: "2024-02-16T21:45:33Z" properties: created_at: example: "2024-02-16T21:45:33Z" type: string created_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string description: example: Standard entity viewing permissions type: string icon: example: entity-icon type: string id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string is_system: example: false type: boolean name: example: Entity Viewer maxLength: 100 minLength: 1 type: string organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string permissions: example: entity: - {} type: object updated_at: example: "2024-02-16T21:45:33Z" type: string required: - is_system - permissions - created_at - updated_at type: object type: array total_count: example: 0 type: integer required: - templates - total_count - offset - limit - has_more type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create permission template description: Create a new permission template. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: description: Standard entity viewing permissions name: Entity Viewer permissions: entity: - {} properties: description: example: Standard entity viewing permissions type: string name: example: Entity Viewer maxLength: 100 minLength: 1 type: string permissions: example: entity: - {} type: object required: - permissions type: object example: description: Standard entity viewing permissions name: Entity Viewer permissions: entity: - {} responses: "201": description: Resource created successfully content: application/json: schema: example: created_at: "2024-02-16T21:45:33Z" created_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Standard entity viewing permissions icon: entity-icon id: 123e4567-e89b-12d3-a456-426614174000 is_system: false name: Entity Viewer organization_id: 123e4567-e89b-12d3-a456-426614174000 permissions: entity: - {} updated_at: "2024-02-16T21:45:33Z" properties: created_at: example: "2024-02-16T21:45:33Z" type: string created_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string description: example: Standard entity viewing permissions type: string icon: example: entity-icon type: string id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string is_system: example: false type: boolean name: example: Entity Viewer maxLength: 100 minLength: 1 type: string organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string permissions: example: entity: - {} type: object updated_at: example: "2024-02-16T21:45:33Z" type: string required: - is_system - permissions - created_at - updated_at type: object example: created_at: "2024-02-16T21:45:33Z" created_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Standard entity viewing permissions icon: entity-icon id: 123e4567-e89b-12d3-a456-426614174000 is_system: false name: Entity Viewer organization_id: 123e4567-e89b-12d3-a456-426614174000 permissions: entity: - {} updated_at: "2024-02-16T21:45:33Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/templates/{templateId}: get: summary: Get permission template description: Get a specific permission template by ID. Requires organization context. tags: - Authorization parameters: - name: templateId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: created_at: "2024-02-16T21:45:33Z" created_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Standard entity viewing permissions icon: entity-icon id: 123e4567-e89b-12d3-a456-426614174000 is_system: false name: Entity Viewer organization_id: 123e4567-e89b-12d3-a456-426614174000 permissions: entity: - {} updated_at: "2024-02-16T21:45:33Z" properties: created_at: example: "2024-02-16T21:45:33Z" type: string created_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string description: example: Standard entity viewing permissions type: string icon: example: entity-icon type: string id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string is_system: example: false type: boolean name: example: Entity Viewer maxLength: 100 minLength: 1 type: string organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string permissions: example: entity: - {} type: object updated_at: example: "2024-02-16T21:45:33Z" type: string required: - is_system - permissions - created_at - updated_at type: object example: created_at: "2024-02-16T21:45:33Z" created_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 description: Standard entity viewing permissions icon: entity-icon id: 123e4567-e89b-12d3-a456-426614174000 is_system: false name: Entity Viewer organization_id: 123e4567-e89b-12d3-a456-426614174000 permissions: entity: - {} updated_at: "2024-02-16T21:45:33Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/permissions/tree: post: summary: Get permission inheritance tree description: Visualize the inheritance tree for a resource permission. Requires organization context. tags: - Authorization requestBody: required: true content: application/json: schema: example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string type: object example: relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 responses: "200": description: Successful response content: application/json: schema: example: final_reason: Permission granted through direct assignment nodes: - {} organization_id: 123e4567-e89b-12d3-a456-426614174000 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: final_reason: example: Permission granted through direct assignment type: string nodes: example: - {} items: example: depth: 0 reason: Direct permission granted source_path: - org:123e4567-e89b-12d3-a456-426614174000 subject: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: depth: example: 0 type: integer reason: example: Direct permission granted type: string source_path: example: - org:123e4567-e89b-12d3-a456-426614174000 - team:456e7890-1234-5678-9abc-def012345678 items: type: string type: array subject: example: user:f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string required: - reason - depth type: object type: array organization_id: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string required: - nodes - final_reason type: object example: final_reason: Permission granted through direct assignment nodes: - {} organization_id: 123e4567-e89b-12d3-a456-426614174000 relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/authorization/users/{userId}/permissions: get: summary: Get user permissions description: Get all permissions for a specific user. Requires organization context. tags: - Authorization parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: direct_permissions: - {} inherited_permissions: [] total_count: 1 user_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: direct_permissions: example: - {} items: example: granted_at: "2024-02-16T21:45:33Z" granted_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 inheritance_source: direct relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: granted_at: example: "2024-02-16T21:45:33.123456789Z" type: string granted_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string inheritance_path: example: org:550e8400-e29b-41d4-a716-446655440000#member -> team:6ba7b810-9dad-11d1-80b4-00c04fd430c8#member type: string inheritance_source: enum: - direct - inherited - template example: direct type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string required: - inheritance_source type: object type: array inherited_permissions: example: - {} items: example: granted_at: "2024-02-16T21:45:33Z" granted_by: a1b2c3d4-e5f6-7890-abcd-ef1234567890 inheritance_source: direct relation: viewer resource: entity:123e4567-e89b-12d3-a456-426614174000 properties: granted_at: example: "2024-02-16T21:45:33.123456789Z" type: string granted_by: example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string inheritance_path: example: org:550e8400-e29b-41d4-a716-446655440000#member -> team:6ba7b810-9dad-11d1-80b4-00c04fd430c8#member type: string inheritance_source: enum: - direct - inherited - template example: direct type: string relation: example: viewer type: string resource: example: entity:123e4567-e89b-12d3-a456-426614174000 type: string required: - inheritance_source type: object type: array total_count: example: 1 type: integer user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - direct_permissions - inherited_permissions - total_count type: object example: direct_permissions: - {} inherited_permissions: [] total_count: 1 user_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "429": description: Too Many Requests content: application/json: schema: properties: category: example: RATE_LIMIT_EXCEEDED type: string code: example: 429 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Too Many Requests type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities: post: summary: Create entity description: Creates a new entity. tags: - Entities parameters: - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: example: affiliation: FRIEND category: DEVICE expires_at: "2029-12-31T23:59:59Z" is_active: true metadata: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical name: Axis IP Camera parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: active type: Camera properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object expires_at: example: "2029-12-31T23:59:59Z" type: string is_active: example: false type: boolean metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string required: - name - category - type - status type: object example: affiliation: FRIEND category: DEVICE expires_at: "2029-12-31T23:59:59Z" is_active: true metadata: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical name: Axis IP Camera parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: active type: Camera responses: "200": description: Idempotent response content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "201": description: Created content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}: delete: summary: Delete entity description: Deletes an entity and their associated data. tags: - Entities parameters: - name: entityId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get entity by ID description: Retrieves a specific entity by their ID. tags: - Entities parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean responses: "200": description: Successful response content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update entity description: Updates an entity's information. tags: - Entities parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: example: affiliation: NEUTRAL category: SENSOR expires_at: "2030-06-15T12:00:00Z" is_active: false metadata: accuracy: ±0.5°C, ±3%RH interface: I2C power: 3.3V range: -40°C to 80°C sensor_type: environmental name: Thermal Imaging Camera parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: operational type: PTZ Camera properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: NEUTRAL type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: SENSOR type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object expires_at: example: "2030-06-15T12:00:00Z" type: - string - "null" is_active: example: false type: - boolean - "null" metadata: additionalProperties: true example: accuracy: ±0.5°C, ±3%RH interface: I2C power: 3.3V range: -40°C to 80°C sensor_type: environmental type: object name: example: Thermal Imaging Camera type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: operational type: string type: example: PTZ Camera type: string type: object example: affiliation: NEUTRAL category: SENSOR expires_at: "2030-06-15T12:00:00Z" is_active: false metadata: accuracy: ±0.5°C, ±3%RH interface: I2C power: 3.3V range: -40°C to 80°C sensor_type: environmental name: Thermal Imaging Camera parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: operational type: PTZ Camera responses: "200": description: Successful response content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}/locations: get: summary: Get paginated entity locations by entity ID description: Retrieves all entity locations that belong to the specific entity ID. tags: - Entity Locations parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string paging: example: has_more: true next: 2 previous: null properties: has_more: example: true type: boolean next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: integer required: - results - paging - crs type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create entity location tags: - Entity Locations parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 1 - 0 - 0 items: type: number type: array type: array crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2023-10-01T12:00:00Z" type: string source: example: Helios type: string velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - position - source type: object responses: "201": description: Created content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}/locations/{entityLocationId}: get: summary: Get entity location that belongs to the entity by ID description: Retrieves a specific entity location that belongs to an entity by their ID. tags: - Entity Locations parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: entityLocationId in: path required: true schema: format: uuid type: string - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string responses: "200": description: Successful response content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}/relationships: get: summary: List entity relationships description: Lists relationships whose source is the URL-path entity. Supports optional filters by relationship type and a created_at time range (created_after, created_before), plus limit/offset pagination. tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: created_after in: query required: false schema: example: "2024-01-01T00:00:00Z" type: string - name: created_before in: query required: false schema: example: "2024-12-31T23:59:59Z" type: string - name: limit in: query required: false schema: default: 50 example: 50 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer - name: type in: query required: false schema: example: DERIVED_FROM type: string responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: example: [] items: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object type: array total_count: example: 3 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create entity relationship description: 'Creates a single relationship whose source is the URL-path entity. Every non-empty (source, type) group has exactly one primary: the first row of an empty group must be is_primary=true (else 400), and is_primary=true on a non-empty group atomically demotes the existing primary in the same transaction.' tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string required: - target_entity_id - type - is_primary type: object responses: "201": description: Created content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}/relationships/{relationshipId}: delete: summary: Delete entity relationship description: 'Soft-deletes a relationship. Idempotent: missing relationships still return 204. Deleting the current primary while other active rows exist in the same (source, type) group is rejected with 409; promote a different row first. Deleting a non-primary row, or a primary that is the last active row in its group, proceeds normally.' tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: relationshipId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get entity relationship by ID description: Retrieves a single relationship anchored on the URL-path source entity. tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: relationshipId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update entity relationship description: Updates is_primary and/or properties on a relationship. Promoting (is_primary=true) atomically demotes the current primary in the same (source, type) group. Demoting the current primary (is_primary=false on the row that is primary) is rejected with 409 because it would leave a non-empty group with zero primaries; hand off primary status by promoting a different row instead. tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: relationshipId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: is_primary: true properties: "2023-12-15T14:30:00Z" properties: is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object type: object example: is_primary: true properties: "2023-12-15T14:30:00Z" responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/{entityId}/relationships/batch: post: summary: Batch create entity relationships description: 'Creates multiple relationships sharing the same source entity in a single request. The exactly-one-primary invariant is enforced per item in order; later items in the same (source, type) group observe the state produced by earlier items. Any item that violates the invariant rolls back the entire batch. Items whose (source, target, type) already exists as an active relationship are idempotent re-sends: the stored properties are overwritten with the item''s properties, is_primary is ignored (use PUT on the relationship to change the primary), and the existing row is returned. This differs from the single-create endpoint, which rejects duplicates with 409.' tags: - Entity Relationships parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: relationships: [] properties: relationships: example: - {} items: properties: is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string required: - target_entity_id - type - is_primary type: object type: array required: - relationships type: object example: relationships: [] responses: "201": description: Created content: application/json: schema: example: [] items: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object type: array example: [] "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/locations/search: post: summary: Search entity locations description: Search entity locations with complex filtering and pagination tags: - Entity Locations parameters: - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string filters: properties: categories: example: - DEVICE - SENSOR items: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK type: string type: array created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string entity_ids: example: - c3d4e5f6-a1b2-7890-1234-567890abcdef - f6a1b2c3-d4e5-7890-1234-567890abcdef items: format: uuid type: string type: array proximity_filter: example: position: - 4.51759087e+06 - 0 - 4.48734841e+06 radius: 250 properties: crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string position: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array radius: example: 250 type: number required: - position - radius type: object recorded_after: example: "2024-01-01T00:00:00Z" type: string recorded_before: example: "2024-12-31T23:59:59Z" type: string sources: example: - Helios - KALMAN_FILTER items: type: string type: array type: object hydrate_entities: example: true type: boolean latest_only: example: true type: boolean sort: items: example: field: created_at order: desc properties: field: enum: - id - entity_id - position - orientation - recorded_at - created_at - velocity - angular_velocity example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string paging: example: has_more: true next: 2 previous: null properties: has_more: example: true type: boolean next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: integer required: - results - paging - crs type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/relationships/search: post: summary: Search entity relationships description: Reverse-lookup search by target entity IDs. Answers \"which entities point at these targets?\" tags: - Entity Relationships parameters: - name: created_after in: query required: false schema: example: "2024-01-01T00:00:00Z" type: string - name: created_before in: query required: false schema: example: "2024-12-31T23:59:59Z" type: string - name: limit in: query required: false schema: default: 50 example: 50 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer - name: type in: query required: false schema: example: DERIVED_FROM type: string requestBody: required: true content: application/json: schema: example: filters: target_entity_ids: - e5f6a1b2-c3d4-7890-1234-567890abcdef - c3d4e5f6-a1b2-7890-1234-567890abcdef types: - DERIVED_FROM - FUSED_FROM sort: - {} properties: filters: example: created_after: "2024-01-01T00:00:00Z" created_before: "2024-12-31T23:59:59Z" target_entity_ids: - e5f6a1b2-c3d4-7890-1234-567890abcdef - c3d4e5f6-a1b2-7890-1234-567890abcdef types: - DERIVED_FROM - FUSED_FROM properties: created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string target_entity_ids: example: - e5f6a1b2-c3d4-7890-1234-567890abcdef - c3d4e5f6-a1b2-7890-1234-567890abcdef items: format: uuid type: string type: array types: example: - DERIVED_FROM - FUSED_FROM items: type: string type: array required: - target_entity_ids type: object sort: items: example: field: created_at order: desc properties: field: enum: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array required: - filters type: object example: filters: target_entity_ids: - e5f6a1b2-c3d4-7890-1234-567890abcdef - c3d4e5f6-a1b2-7890-1234-567890abcdef types: - DERIVED_FROM - FUSED_FROM sort: - {} responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: example: [] items: properties: created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: format: uuid type: string is_primary: example: true type: boolean properties: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object source_entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string target_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string type: example: DERIVED_FROM type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - source_entity_id - target_entity_id - type - is_primary - created_at - updated_at type: object type: array total_count: example: 3 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/entities/search: post: summary: Search entities description: Search entities with complex filtering and pagination tags: - Entities parameters: - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: properties: filters: properties: affiliation: example: - FRIEND - NEUTRAL items: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED type: string type: array category: example: - DEVICE - SENSOR items: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK type: string type: array created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string entity_ids: example: - c3d4e5f6-a1b2-7890-1234-567890abcdef - e5f6a1b2-c3d4-7890-1234-567890abcdef items: format: uuid type: string type: array expires_after: example: "2025-01-01T00:00:00Z" type: string expires_before: example: "2026-12-31T23:59:59Z" type: string is_active: example: true type: boolean name: example: Camera type: string parent_ids: example: - a1b2c3d4-e5f6-7890-1234-567890abcdef items: format: uuid type: string type: array status: items: type: string type: array top_classifications: example: - HUMAN - VEHICLE items: type: string type: array types: example: - Camera - Environmental items: type: string type: array updated_after: example: "2024-02-01T00:00:00Z" type: string updated_before: example: "2024-03-31T23:59:59Z" type: string type: object sort: items: example: field: created_at order: desc properties: field: enum: - name - status - type - category - affiliation - organization_id - created_at - updated_at - expires_at - is_active - id - top_classification - recorded_at - position - orientation - entity_id - parent_id example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array with_location_latest: example: false type: boolean type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions: post: summary: Create event subscription description: Creates a new event subscription. tags: - Event-Subscriptions requestBody: required: true content: application/json: schema: example: alert_window: null delivery_frequency: null event_types: null filters: null is_enabled: null last_triggered_at: "2023-12-15T14:30:00Z" min_interval: null organization_id: null properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: minimum: 0 type: integer user_id: format: uuid type: string required: - user_id - event_types - delivery_frequency - alert_window - is_enabled - min_interval type: object example: alert_window: null delivery_frequency: null event_types: null filters: null is_enabled: null last_triggered_at: "2023-12-15T14:30:00Z" min_interval: null organization_id: null responses: "201": description: Created content: application/json: schema: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object created_at: example: "2023-12-15T14:30:00Z" type: string delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object id: format: uuid type: string is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: type: integer organization_id: format: uuid type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - organization_id - user_id - event_types - delivery_frequency - alert_window - is_enabled - created_at - updated_at - min_interval type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/{eventSubscriptionId}: delete: summary: Delete event subscription description: Deletes an event subscription and its associated data. tags: - Event-Subscriptions parameters: - name: eventSubscriptionId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get event subscription by ID description: Retrieves a specific subscription by their ID. tags: - Event-Subscriptions parameters: - name: eventSubscriptionId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object created_at: example: "2023-12-15T14:30:00Z" type: string delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object id: format: uuid type: string is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: type: integer organization_id: format: uuid type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - organization_id - user_id - event_types - delivery_frequency - alert_window - is_enabled - created_at - updated_at - min_interval type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update event subscription description: Updates an event subscription's information. tags: - Event-Subscriptions parameters: - name: eventSubscriptionId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: alert_window: null delivery_frequency: null event_types: - DEVICE_CREATED filters: actor_id: jkfg3hf6-a1b2-7890-1234-567890abcdzs is_enabled: null last_triggered_at: "2023-12-15T14:30:00Z" min_interval: null properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: minimum: 0 type: integer type: object example: alert_window: null delivery_frequency: null event_types: - DEVICE_CREATED filters: actor_id: jkfg3hf6-a1b2-7890-1234-567890abcdzs is_enabled: null last_triggered_at: "2023-12-15T14:30:00Z" min_interval: null responses: "200": description: Successful response content: application/json: schema: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object created_at: example: "2023-12-15T14:30:00Z" type: string delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object id: format: uuid type: string is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: type: integer organization_id: format: uuid type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - organization_id - user_id - event_types - delivery_frequency - alert_window - is_enabled - created_at - updated_at - min_interval type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/{eventSubscriptionId}/channels/all: get: summary: Get all event subscription channels for an event subscription description: Retrieves all subscription channels that belong to an event subscription. tags: - Event-Subscriptions parameters: - name: eventSubscriptionId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: channel: enum: - EMAIL - SMS type: string created_at: example: "2025-09-24T10:00:00Z" type: string destination: example: user@example.com type: string event_subscription_id: format: uuid type: string id: format: uuid type: string is_verified: example: true type: boolean metadata: example: template: welcome-email type: object updated_at: example: "2025-09-24T10:30:00Z" type: string required: - id - event_subscription_id - channel - destination - is_verified - created_at - updated_at type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/channels: post: summary: Create event subscription channel description: Creates a new event subscription channel. tags: - Event-Subscriptions requestBody: required: true content: application/json: schema: properties: channel: enum: - EMAIL - SMS type: string destination: example: user@example.com type: string event_subscription_id: format: uuid type: string metadata: example: template: welcome-email type: object required: - event_subscription_id - channel - destination type: object responses: "201": description: Created content: application/json: schema: properties: channel: enum: - EMAIL - SMS type: string created_at: example: "2025-09-24T10:00:00Z" type: string destination: example: user@example.com type: string event_subscription_id: format: uuid type: string id: format: uuid type: string is_verified: example: true type: boolean metadata: example: template: welcome-email type: object updated_at: example: "2025-09-24T10:30:00Z" type: string required: - id - event_subscription_id - channel - destination - is_verified - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/channels/{eventSubscriptionChannelId}: delete: summary: Delete event subscription channel description: Deletes an event subscription channel and its associated data. tags: - Event-Subscriptions parameters: - name: eventSubscriptionChannelId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get event subscription channel by ID description: Retrieves a specific subscription channel by their ID. tags: - Event-Subscriptions parameters: - name: eventSubscriptionChannelId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: channel: enum: - EMAIL - SMS type: string created_at: example: "2025-09-24T10:00:00Z" type: string destination: example: user@example.com type: string event_subscription_id: format: uuid type: string id: format: uuid type: string is_verified: example: true type: boolean metadata: example: template: welcome-email type: object updated_at: example: "2025-09-24T10:30:00Z" type: string required: - id - event_subscription_id - channel - destination - is_verified - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update event subscription channel description: Updates an event subscription channel's information. tags: - Event-Subscriptions parameters: - name: eventSubscriptionChannelId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: channel: enum: - EMAIL - SMS type: string destination: example: "+15559876543" type: string is_enabled: type: boolean is_verified: type: boolean metadata: example: headers: X-Test: "Y" type: object type: object responses: "200": description: Successful response content: application/json: schema: properties: channel: enum: - EMAIL - SMS type: string created_at: example: "2025-09-24T10:00:00Z" type: string destination: example: user@example.com type: string event_subscription_id: format: uuid type: string id: format: uuid type: string is_verified: example: true type: boolean metadata: example: template: welcome-email type: object updated_at: example: "2025-09-24T10:30:00Z" type: string required: - id - event_subscription_id - channel - destination - is_verified - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/search: post: summary: Search event subscriptions description: Search event subscriptions with complex filtering and pagination tags: - Event-Subscriptions parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: filters: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object is_enabled: type: boolean user_id: format: uuid type: string type: object organization_id: format: uuid type: string sort: example: - {} - {} items: properties: field: enum: - created_at - updated_at - is_enabled - delivery_frequency example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object created_at: example: "2023-12-15T14:30:00Z" type: string delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object id: format: uuid type: string is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: type: integer organization_id: format: uuid type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - organization_id - user_id - event_types - delivery_frequency - alert_window - is_enabled - created_at - updated_at - min_interval type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/event-subscriptions/users/{userId}: get: summary: Get event subscriptions for a user description: Retrieves a user's subscriptions. tags: - Event-Subscriptions parameters: - name: userId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: alert_window: properties: days: example: [] items: maximum: 6 minimum: 0 type: integer type: array end_time: example: "18:00" type: string start_time: example: "08:00" type: string timezone: example: America/New_York type: string required: - days - start_time - end_time - timezone type: object created_at: example: "2023-12-15T14:30:00Z" type: string delivery_frequency: enum: - IMMEDIATE - HOURLY - DAILY - WEEKLY type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array filters: properties: actor_ids: example: - 550e8400-e29b-41d4-a716-446655440000 items: format: uuid type: string type: array actor_type: enum: - USER - ENTITY - OTHER example: USER type: string type: object id: format: uuid type: string is_enabled: type: boolean last_triggered_at: example: "2023-12-15T14:30:00Z" type: string min_interval: type: integer organization_id: format: uuid type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - organization_id - user_id - event_types - delivery_frequency - alert_window - is_enabled - created_at - updated_at - min_interval type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/events: get: summary: Get all events description: Retrieves all events with pagination and filtering options. tags: - Events parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/events/{eventId}: get: summary: Get event by ID description: Retrieves a specific event by their ID. tags: - Events parameters: - name: eventId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/events/search: post: summary: Search events description: Search events with complex filtering and pagination tags: - Events parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: filters: properties: actor_ids: items: format: uuid type: string type: array actor_types: items: enum: - USER - ENTITY - OTHER example: ENTITY type: string type: array after_event_timestamp: type: string before_event_timestamp: type: string created_after: type: string created_before: type: string event_description: type: string event_types: items: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string type: array source_ids: items: format: uuid type: string type: array type: object sort: items: properties: field: enum: - id - source_id - created_at - organization_id - event_type - metadata - event_description - actor_id - actor_type - event_timestamp type: string order: enum: - asc - desc type: string required: - field - order type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation: get: summary: List the active Legion roster for the current org description: Returns the federation Legion roster (NATS siblings) for the active organization. Requires org:viewer. tags: - Federation parameters: - name: limit in: query required: false schema: default: 100 maximum: 500 minimum: 1 type: number - name: offset in: query required: false schema: default: 0 minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: limit: type: number offset: type: number peers: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at type: object type: array total: type: number required: - peers - total - limit - offset type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation/{id}: get: summary: Get a Legion by ID description: Returns the Legion's roster entry (hostname, overlay IP, status, active cert metadata). Mesh-only machines are read via /v3/mesh and 404 here. Requires org:viewer on the Legion's owning org. tags: - Federation parameters: - name: id in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation/{id}/renew: post: summary: Renew a Legion's certificates description: Issues a fresh Nebula certificate plus refreshed NATS account material for an existing Legion. Mesh-only machines renew via /v3/mesh and 404 here. The owning org is resolved from the path parameter. Requires org:operator on that org. tags: - Federation parameters: - name: id in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: cert_not_after: type: string files: additionalProperties: type: string type: object hostname: type: string initial_roster: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at type: object type: array ip: type: string lan_subnet: type: string lighthouses: items: properties: endpoints: items: type: string type: array ip: type: string required: - ip - endpoints type: object type: array machine_id: format: uuid type: string nats_url: type: string required: - machine_id - hostname - ip - cert_not_after - files - lighthouses - initial_roster type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation/{id}/revoke: post: summary: Revoke a Legion description: Marks a Legion revoked, revokes its certs, deny-lists its NATS account NKey, and emits a roster event. Mesh-only machines are revoked via /v3/mesh and 404 here. Requires org:admin and a non-integration token. tags: - Federation parameters: - name: id in: path required: true schema: format: uuid type: string requestBody: content: application/json: schema: properties: reason: type: string type: object responses: "200": description: Successful response content: application/json: schema: properties: machine_id: format: uuid type: string revoked_at: type: string status: type: string required: - machine_id - status - revoked_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation/all: get: summary: List Legions across all orgs description: Returns every Legion across all organizations (mesh-only machines are listed under /v3/mesh/machines instead). Optional status and org-id filters. Requires system admin. tags: - Federation parameters: - name: limit in: query required: false schema: default: 100 maximum: 500 minimum: 1 type: number - name: offset in: query required: false schema: default: 0 minimum: 0 type: number - name: org-id in: query required: false schema: format: uuid type: string - name: status in: query required: false schema: default: ACTIVE enum: - ACTIVE - REVOKED - all type: string responses: "200": description: Successful response content: application/json: schema: properties: limit: type: number offset: type: number peers: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at type: object type: array total: type: number required: - peers - total - limit - offset type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/federation/enroll: post: summary: Enroll a Legion description: Enrolls a new Legion (field or cloud) into the federation overlay. Returns the issued certs, lighthouse list, and an initial peer roster. Requires org:operator. tags: - Federation requestBody: required: true content: application/json: schema: properties: entity_id: format: uuid type: string hostname: type: string required: - hostname type: object responses: "201": description: Resource created successfully content: application/json: schema: properties: cert_not_after: type: string files: additionalProperties: type: string type: object hostname: type: string initial_roster: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at type: object type: array ip: type: string lan_subnet: type: string lighthouses: items: properties: endpoints: items: type: string type: array ip: type: string required: - ip - endpoints type: object type: array machine_id: format: uuid type: string nats_url: type: string required: - machine_id - hostname - ip - cert_not_after - files - lighthouses - initial_roster type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/data/{feedId}: get: summary: Get feed data by item ID description: Retrieves a specific feed data item by its unique stable ID tags: - Feed Data parameters: - name: feedId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" properties: blob_content_type: example: application/json type: string blob_key: example: feed-data/2024/03/15/sensor_data_abc123.json type: string blob_metadata: type: object blob_size_bytes: example: 2048 type: number blob_storage_type: example: S3 type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string payload: example: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" type: object received_at: example: "2024-03-11T16:00:00Z" type: string recorded_at: example: "2024-01-15T11:00:00Z" type: string required: - id - organization_id - recorded_at - received_at - entity_id - feed_definition_id type: object example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/data/{feedId}/detections/{detectionEntityId}/feedback: get: summary: Get feedback for a detection on a feed data entry description: Returns paginated feedback entries for a specific detection within a feed data item tags: - Feed Data parameters: - name: detectionEntityId in: path required: true schema: format: uuid type: string - name: feedId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: comment: example: Wrong class type: string created_at: example: "2024-01-15T11:00:00Z" type: string created_by: format: uuid type: string detection_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feedback_type: example: false_positive type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string sentiment: example: "2023-12-15T14:30:00Z" type: string target_feed_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string required: - id - organization_id - target_feed_id - entity_id - detection_entity_id - sentiment - feedback_type - created_at type: object type: array total_count: example: 1 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Submit feedback for a detection on a feed data entry description: Submits structured feedback for a specific detection within a feed data item tags: - Feed Data parameters: - name: detectionEntityId in: path required: true schema: format: uuid type: string - name: feedId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: comment: type: string feedback_type: example: false_positive type: string sentiment: example: "2023-12-15T14:30:00Z" type: string required: - sentiment - feedback_type type: object responses: "201": description: Created content: application/json: schema: properties: comment: example: Wrong class type: string created_at: example: "2024-01-15T11:00:00Z" type: string created_by: format: uuid type: string detection_entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feedback_type: example: false_positive type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string sentiment: example: "2023-12-15T14:30:00Z" type: string target_feed_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string required: - id - organization_id - target_feed_id - entity_id - detection_entity_id - sentiment - feedback_type - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/data/{feedId}/detections/{detectionEntityId}/feedback/{feedbackId}: delete: summary: Delete feedback for a detection on a feed data entry description: Soft-deletes feedback for a specific detection. Users may only delete feedback they submitted. tags: - Feed Data parameters: - name: detectionEntityId in: path required: true schema: format: uuid type: string - name: feedId in: path required: true schema: format: uuid type: string - name: feedbackId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/definitions: post: summary: Create feed definition description: Creates a new feed definition tags: - Feed Definitions requestBody: required: true content: application/json: schema: properties: category: enum: - MESSAGE - FILE type: string data_type: example: application/json type: string description: example: Temperature readings from IoT sensors type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string feed_name: example: temperature_readings type: string integration_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object schema_definition: type: object template_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string required: - category - feed_name - data_type - is_active - is_template type: object responses: "201": description: Created content: application/json: schema: example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" properties: category: enum: - MESSAGE - FILE example: MESSAGE type: string created_at: example: "2024-01-15T11:00:00Z" type: string data_type: example: application/json type: string description: example: Real-time sensor telemetry data from field devices type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_name: example: sensor_telemetry type: string id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string integration_id: format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string schema_definition: example: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object type: object template_id: format: uuid type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - category - feed_name - data_type - is_active - is_template - created_at - updated_at type: object example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/definitions/{feedDefinitionId}: delete: summary: Delete feed definition description: Deletes an existing feed definition tags: - Feed Definitions parameters: - name: feedDefinitionId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get feed definition by ID description: Retrieves a specific feed definition by its ID tags: - Feed Definitions parameters: - name: feedDefinitionId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" properties: category: enum: - MESSAGE - FILE example: MESSAGE type: string created_at: example: "2024-01-15T11:00:00Z" type: string data_type: example: application/json type: string description: example: Real-time sensor telemetry data from field devices type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_name: example: sensor_telemetry type: string id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string integration_id: format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string schema_definition: example: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object type: object template_id: format: uuid type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - category - feed_name - data_type - is_active - is_template - created_at - updated_at type: object example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update feed definition description: Updates an existing feed definition tags: - Feed Definitions parameters: - name: feedDefinitionId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: category: enum: - MESSAGE - FILE type: string data_type: example: image/jpeg type: string description: example: Image uploads from mobile devices type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string feed_name: example: image_uploads type: string integration_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object schema_definition: type: object template_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string required: - category - feed_name - data_type - is_active - is_template type: object responses: "200": description: Successful response content: application/json: schema: example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" properties: category: enum: - MESSAGE - FILE example: MESSAGE type: string created_at: example: "2024-01-15T11:00:00Z" type: string data_type: example: application/json type: string description: example: Real-time sensor telemetry data from field devices type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_name: example: sensor_telemetry type: string id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string integration_id: format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string schema_definition: example: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object type: object template_id: format: uuid type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - category - feed_name - data_type - is_active - is_template - created_at - updated_at type: object example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/definitions/search: post: summary: Search feed definitions description: Search feed definitions with filtering and pagination tags: - Feed Definitions parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: category: enum: - MESSAGE - FILE example: - MESSAGE - FILE type: string created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string data_type: example: - application/json - image/jpeg type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string feed_name: example: sensor_telemetry type: string integration_id: format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string template_id: format: uuid type: string type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: example: - category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" items: example: category: MESSAGE created_at: "2023-12-15T14:30:00Z" data_type: application/json description: Real-time sensor telemetry data from field devices entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_name: sensor_telemetry id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef is_active: "true" is_template: "false" metadata: processing_pipeline: temperature_normalization retention_policy: 30d source: IoT Gateway update_frequency: 5s organization_id: 550e8400-e29b-41d4-a716-446655440000 schema_definition: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object template_id: f47ac10b-58cc-4372-a567-0e02b2c3d480 updated_at: "2023-12-15T14:30:00Z" properties: category: enum: - MESSAGE - FILE example: MESSAGE type: string created_at: example: "2024-01-15T11:00:00Z" type: string data_type: example: application/json type: string description: example: Real-time sensor telemetry data from field devices type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_name: example: sensor_telemetry type: string id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string integration_id: format: uuid type: string is_active: example: true type: boolean is_template: example: false type: boolean metadata: type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string schema_definition: example: $schema: http://json-schema.org/draft-07/schema# properties: humidity: description: Humidity percentage maximum: 100 minimum: 0 type: number temperature: description: Temperature in Celsius maximum: 100 minimum: -50 type: number timestamp: description: Measurement timestamp format: date-time type: string required: - temperature - humidity - timestamp type: object type: object template_id: format: uuid type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - category - feed_name - data_type - is_active - is_template - created_at - updated_at type: object type: array total_count: example: 18 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/entities/{entityId}/{feedName}/data/latest: get: summary: Get latest feed data by entity and feed name description: Retrieves the latest feed data for a specific entity using a human-readable feed name instead of a feed definition UUID tags: - Feed Data parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: feedName in: path required: true schema: type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" properties: blob_content_type: example: application/json type: string blob_key: example: feed-data/2024/03/15/sensor_data_abc123.json type: string blob_metadata: type: object blob_size_bytes: example: 2048 type: number blob_storage_type: example: S3 type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string payload: example: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" type: object received_at: example: "2024-03-11T16:00:00Z" type: string recorded_at: example: "2024-01-15T11:00:00Z" type: string required: - id - organization_id - recorded_at - received_at - entity_id - feed_definition_id type: object type: array total_count: example: 158 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/entities/{entityId}/definitions/{feedDefinitionId}/data/latest: get: summary: Get latest feed data by entity and feed definition description: Retrieves the latest feed data for a specific entity and feed definition tags: - Feed Data parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: feedDefinitionId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" properties: blob_content_type: example: application/json type: string blob_key: example: feed-data/2024/03/15/sensor_data_abc123.json type: string blob_metadata: type: object blob_size_bytes: example: 2048 type: number blob_storage_type: example: S3 type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string payload: example: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" type: object received_at: example: "2024-03-11T16:00:00Z" type: string recorded_at: example: "2024-01-15T11:00:00Z" type: string required: - id - organization_id - recorded_at - received_at - entity_id - feed_definition_id type: object type: array total_count: example: 158 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/entities/{entityId}/latest: get: summary: Get latest feed data for entity description: Retrieves the latest feed data for a specific entity across all feed definitions tags: - Feed Data parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" properties: blob_content_type: example: application/json type: string blob_key: example: feed-data/2024/03/15/sensor_data_abc123.json type: string blob_metadata: type: object blob_size_bytes: example: 2048 type: number blob_storage_type: example: S3 type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string payload: example: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" type: object received_at: example: "2024-03-11T16:00:00Z" type: string recorded_at: example: "2024-01-15T11:00:00Z" type: string required: - id - organization_id - recorded_at - received_at - entity_id - feed_definition_id type: object type: array total_count: example: 158 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/files: post: summary: Upload feed file data description: 'Upload file-based feed data using multipart/form-data. The request must contain a ''metadata_json_payload'' form field with JSON metadata matching the IngestFeedFileDataRequest schema, and a ''fileContent'' form field with the binary file content. Note: The stored file name, size and mime_type are computed by the server from client-supplied inputs: the file name is a sanitized form of the multipart filename, the size is measured from the uploaded bytes, and the content type is taken from file_content_type, then the part''s Content-Type header. A supplied value of application/octet-stream is replaced by the type implied by the filename extension when the extension is recognized. When no value is supplied, or the supplied value cannot be parsed as a media type, the filename extension is tried first and detection from the file content is used only when the extension is not recognized. A value that parses to any other media type is used as-is: if it is unsupported it is rejected rather than passed to detection. The resulting content type must be one of application/json, application/octet-stream, application/pdf, application/zip, image/gif, image/jpeg, image/png, image/webp, text/csv, text/plain, video/mp4. Anything else is rejected with 400.' tags: - Feed Data requestBody: required: true content: multipart/form-data: schema: properties: fileContent: description: Binary file content format: binary type: string metadata_json_payload: properties: blob_metadata: type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: f7a8b9c0-d1e2-3f4a-5b6c-7d8e9f0a1b2c format: uuid type: string file_content_type: type: string recorded_at: example: "2024-02-16T21:45:33Z" type: string required: - entity_id - feed_definition_id - recorded_at type: object required: - metadata_json_payload - fileContent type: object responses: "200": description: Successful response content: application/json: schema: properties: blob_key: type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: f7a8b9c0-d1e2-3f4a-5b6c-7d8e9f0a1b2c format: uuid type: string file_content_type: type: string file_size_bytes: type: number file_storage_type: example: S3 type: string recorded_at: example: "2024-02-16T21:45:33Z" type: string uploaded_at: example: "2024-02-16T21:45:40Z" type: string required: - blob_key - file_storage_type - file_size_bytes - uploaded_at - entity_id - feed_definition_id - recorded_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "413": description: Payload Too Large content: application/json: schema: properties: category: example: PAYLOAD_TOO_LARGE type: string code: example: 413 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Payload Too Large type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "415": description: Unsupported Media Type content: application/json: schema: properties: category: example: UNSUPPORTED_MEDIA_TYPE type: string code: example: 415 type: number details: items: properties: field: example: field_name type: string issue: example: Field validation issue type: string type: object type: array message: example: Unsupported Media Type type: string status: example: error type: string timestamp: example: "2024-03-15T10:30:00Z" type: string trace_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/files/download: get: summary: Download feed file data description: Download file content by blob key. Returns the binary file content with appropriate headers. tags: - Feed Data parameters: - name: key in: query required: true schema: example: c3d4e5f6-a1b2-4789-9234-567890abcdef pattern: ^[A-Za-z0-9._-]{1,128}$ type: string responses: "200": description: Successful response "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/messages: post: summary: Ingest message feed data description: Ingest new message-based feed data into the system tags: - Feed Data requestBody: required: true content: application/json: schema: properties: entity_id: format: uuid type: string feed_definition_id: format: uuid type: string metadata: type: object payload: type: object recorded_at: type: string required: - entity_id - feed_definition_id - recorded_at - payload type: object responses: "202": description: Successful response "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/feeds/search: post: summary: Search feed data description: Search feed data with complex filtering and pagination tags: - Feed Data parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: blob_content_types: example: - application/json - image/jpeg items: type: string type: array blob_storage_types: example: - S3 - GCS items: type: string type: array data_types: example: - application/json - text/plain items: type: string type: array entity_ids: example: - e5f6a1b2-c3d4-7890-1234-567890abcdef - c3d4e5f6-a1b2-7890-1234-567890abcdef items: format: uuid type: string type: array feed_definition_ids: example: - d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a - a8b9c0d1-e2f3-4a5b-6c7d-8e9f0a1b2c3d items: format: uuid type: string type: array received_after: example: "2024-01-01T00:00:00Z" type: string received_before: example: "2024-12-31T23:59:59Z" type: string recorded_after: example: "2024-01-01T00:00:00Z" type: string recorded_before: example: "2024-12-31T23:59:59Z" type: string sort_fields: example: - {} items: properties: ascending: example: false type: boolean field: example: recorded_at type: string required: - field - ascending type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: blob_content_type: null blob_key: null blob_metadata: null blob_size_bytes: null blob_storage_type: null entity_id: e5f6a1b2-c3d4-7890-1234-567890abcdef feed_definition_id: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a id: 550e8400-e29b-41d4-a716-446655440000 organization_id: 550e8400-e29b-41d4-a716-446655440000 payload: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" received_at: "2024-03-11T16:00:00Z" recorded_at: "2024-01-15T11:00:00Z" properties: blob_content_type: example: application/json type: string blob_key: example: feed-data/2024/03/15/sensor_data_abc123.json type: string blob_metadata: type: object blob_size_bytes: example: 2048 type: number blob_storage_type: example: S3 type: string entity_id: example: e5f6a1b2-c3d4-7890-1234-567890abcdef format: uuid type: string feed_definition_id: example: d5e6f7a8-b9c0-1d2e-3f4a-5b6c7d8e9f0a format: uuid type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string payload: example: humidity: 65.2 pressure: 1013.25 temperature: 25.5 timestamp: "2024-01-15T11:00:00Z" type: object received_at: example: "2024-03-11T16:00:00Z" type: string recorded_at: example: "2024-01-15T11:00:00Z" type: string required: - id - organization_id - recorded_at - received_at - entity_id - feed_definition_id type: object type: array total_count: example: 158 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations: get: summary: List integrations by organization description: Get a list of integrations for the authenticated organization tags: - Integrations parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: example: integrations: - created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" total: 3 properties: integrations: items: example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string description: example: Integration for DJI drone platforms with real-time telemetry and video streaming type: string id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string name: example: Drone Command System type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string status: example: ACTIVE type: string updated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - name - status - created_at - updated_at type: object type: array total: example: 3 type: number required: - integrations - total type: object example: integrations: - created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" total: 3 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create integration description: Create a new integration from a manifest tags: - Integrations requestBody: required: true content: application/json: schema: example: manifest_content: capabilities: - telemetry - video_stream - control categories: - UAV - Command description: Advanced drone command and control integration display_name: Drone Command System name: drone-command-system oauth: redirect_uris: - https://app.example.com/oauth/callback scopes: - entities:read - entities:write - feeds:write type: integration version: 1.0.0 properties: manifest_content: type: object required: - manifest_content type: object example: manifest_content: capabilities: - telemetry - video_stream - control categories: - UAV - Command description: Advanced drone command and control integration display_name: Drone Command System name: drone-command-system oauth: redirect_uris: - https://app.example.com/oauth/callback scopes: - entities:read - entities:write - feeds:write type: integration version: 1.0.0 responses: "201": description: Resource created successfully content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string description: example: Integration for DJI drone platforms with real-time telemetry and video streaming type: string id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string name: example: Drone Command System type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string status: example: ACTIVE type: string updated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - name - status - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/.well-known/jwks.json: get: summary: Get JSON Web Key Set description: Returns the JSON Web Key Set containing public keys used to sign OAuth tokens. Use this to verify token signatures. tags: - OAuth responses: "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/{integration_id}: delete: summary: Delete integration description: Delete an integration and all associated data tags: - Integrations parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get integration description: Get details of a specific integration tags: - Integrations parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string description: example: Integration for DJI drone platforms with real-time telemetry and video streaming type: string id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string name: example: Drone Command System type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string status: example: ACTIVE type: string updated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - name - status - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update integration description: Update an existing integration from a manifest tags: - Integrations parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string requestBody: required: true content: application/json: schema: example: manifest_content: capabilities: - telemetry - video_stream - control categories: - UAV - Command description: Advanced drone command and control integration display_name: Drone Command System name: drone-command-system oauth: redirect_uris: - https://app.example.com/oauth/callback scopes: - entities:read - entities:write - feeds:write type: integration version: 1.0.0 properties: manifest_content: type: object required: - manifest_content type: object example: manifest_content: capabilities: - telemetry - video_stream - control categories: - UAV - Command description: Advanced drone command and control integration display_name: Drone Command System name: drone-command-system oauth: redirect_uris: - https://app.example.com/oauth/callback scopes: - entities:read - entities:write - feeds:write type: integration version: 1.0.0 responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string description: example: Integration for DJI drone platforms with real-time telemetry and video streaming type: string id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string name: example: Drone Command System type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string status: example: ACTIVE type: string updated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - name - status - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: d4e5f6a1-b2c3-7890-1234-567890abcdef name: Drone Command System organization_id: 550e8400-e29b-41d4-a716-446655440000 status: ACTIVE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/{integration_id}/oauth: get: summary: Get OAuth configuration description: Get OAuth configuration for an integration tags: - OAuth parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string responses: "200": description: Successful response content: application/json: schema: example: client_id: integration.drone-cmd integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef organization_id: 550e8400-e29b-41d4-a716-446655440000 redirect_uris: - https://app.example.com/oauth/callback requested_scopes: - entities:read - entities:write - feeds:write properties: client_id: example: integration.drone-cmd type: string integration_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 type: string redirect_uris: example: - https://app.example.com/oauth/callback items: type: string type: array requested_scopes: example: - entities:read - entities:write - feeds:write items: type: string type: array required: - client_id - requested_scopes - redirect_uris - integration_id - organization_id type: object example: client_id: integration.drone-cmd integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef organization_id: 550e8400-e29b-41d4-a716-446655440000 redirect_uris: - https://app.example.com/oauth/callback requested_scopes: - entities:read - entities:write - feeds:write "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/{integration_id}/oauth/secret: get: summary: Get OAuth client secret description: Get OAuth client secret for an integration tags: - OAuth parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string responses: "200": description: Successful response content: application/json: schema: example: client_id: integration.drone-cmd client_secret: cs_abcdef123456789 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef last_rotated_at: "2023-01-01T00:00:00Z" organization_id: 550e8400-e29b-41d4-a716-446655440000 properties: client_id: example: integration.drone-cmd type: string client_secret: example: cs_abcdef123456789 type: string integration_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string last_rotated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string required: - client_id - client_secret - integration_id - organization_id type: object example: client_id: integration.drone-cmd client_secret: cs_abcdef123456789 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef last_rotated_at: "2023-01-01T00:00:00Z" organization_id: 550e8400-e29b-41d4-a716-446655440000 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/{integration_id}/oauth/secret/regenerate: post: summary: Regenerate OAuth client secret description: Regenerate OAuth client secret for an integration tags: - OAuth parameters: - name: integration_id in: path required: true schema: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string responses: "200": description: Successful response content: application/json: schema: example: client_id: integration.drone-cmd client_secret: cs_abcdef123456789 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef last_rotated_at: "2023-01-01T00:00:00Z" organization_id: 550e8400-e29b-41d4-a716-446655440000 properties: client_id: example: integration.drone-cmd type: string client_secret: example: cs_abcdef123456789 type: string integration_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string last_rotated_at: example: "2023-01-01T00:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string required: - client_id - client_secret - integration_id - organization_id type: object example: client_id: integration.drone-cmd client_secret: cs_abcdef123456789 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef last_rotated_at: "2023-01-01T00:00:00Z" organization_id: 550e8400-e29b-41d4-a716-446655440000 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/oauth/authorize: get: summary: OAuth authorization endpoint description: OAuth 2.0 authorization endpoint for integrations tags: - OAuth responses: "200": description: OAuth authorization initiated (for programmatic clients) content: application/json: schema: description: Reference to nil type: object "302": description: Redirect to OAuth provider content: application/json: schema: description: Reference to nil type: object "303": description: Redirect to OAuth provider after authorization content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/oauth/callback: get: summary: OAuth authorization callback description: Handle OAuth authorization callback from OAuth provider tags: - OAuth responses: "200": description: Successful response content: application/json: schema: example: code: auth_code_abc123def456 message: Authorization completed successfully state: state_xyz789 status: success properties: code: example: auth_code_abc123def456 type: string message: example: Authorization completed successfully type: string state: example: state_xyz789 type: string status: example: success type: string required: - status - message type: object example: code: auth_code_abc123def456 message: Authorization completed successfully state: state_xyz789 status: success "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/oauth/revoke: post: summary: OAuth token revocation description: Revoke an OAuth token tags: - OAuth requestBody: required: true content: application/json: schema: example: client_id: integration.drone-cmd client_secret: client_secret_xyz789 token: jwt_access_token_example_placeholder token_type_hint: access_token properties: client_id: example: integration.drone-cmd type: string client_secret: example: client_secret_xyz789 type: string token: example: jwt_access_token_example_placeholder type: string token_type_hint: example: access_token type: string required: - token type: object example: client_id: integration.drone-cmd client_secret: client_secret_xyz789 token: jwt_access_token_example_placeholder token_type_hint: access_token responses: "200": description: Successful response content: application/json: schema: example: message: Token revoked successfully status: success properties: message: example: Token revoked successfully type: string status: example: success type: string required: - status - message type: object example: message: Token revoked successfully status: success "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/oauth/token: post: summary: OAuth token endpoint description: Exchange authorization code or refresh token for access token tags: - OAuth requestBody: required: true content: application/json: schema: example: client_id: integration.drone-cmd code: auth_code_abc123 grant_type: authorization_code redirect_uri: https://app.example.com/oauth/callback properties: client_id: example: integration.drone-cmd type: string client_secret: example: client_secret_xyz789 type: string code: example: auth_code_abc123 type: string code_verifier: example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk pattern: ^[A-Za-z0-9._~-]+$ type: string grant_type: enum: - authorization_code - refresh_token - client_credentials example: authorization_code type: string redirect_uri: example: https://app.example.com/oauth/callback type: string refresh_token: example: rt_refresh_token_example_placeholder type: string required: - grant_type - client_id type: object example: client_id: integration.drone-cmd code: auth_code_abc123 grant_type: authorization_code redirect_uri: https://app.example.com/oauth/callback responses: "200": description: Successful response content: application/json: schema: properties: access_token: example: jwt_access_token_example_placeholder type: string expires_in: example: 3600 type: number refresh_token: example: rt_refresh_token_example_placeholder type: string scope: example: entities:read entities:write feeds:write type: string token_type: example: Bearer type: string required: - access_token - token_type - expires_in - scope type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/integrations/oauth/tokeninfo: get: summary: OAuth token introspection description: Introspect OAuth token to get information about it tags: - OAuth parameters: - name: token in: query required: true schema: example: jwt_access_token_example_placeholder type: string - name: token_type_hint in: query required: false schema: example: access_token type: string responses: "200": description: Successful response content: application/json: schema: example: active: true client_id: integration.drone-cmd exp: 1.6409952e+09 iat: 1.6409916e+09 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef organization_id: 550e8400-e29b-41d4-a716-446655440000 scope: entities:write organizations:read sub: f47ac10b-58cc-4372-a567-0e02b2c3d479 token_type: Bearer user_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 username: user@picogrid.com properties: active: example: true type: boolean aud: example: - https://api.legion.com items: type: string type: array client_id: example: integration.drone-cmd type: string exp: example: 1.6409952e+09 type: number iat: example: 1.6409916e+09 type: number integration_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef type: string iss: example: https://legion.com type: string jti: example: 2b3a4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d type: string nbf: example: 1.6409916e+09 type: number organization_id: example: 550e8400-e29b-41d4-a716-446655440000 type: string scope: example: entities:write organizations:read type: string sub: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string token_type: example: Bearer type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 type: string username: example: user@picogrid.com type: string required: - active type: object example: active: true client_id: integration.drone-cmd exp: 1.6409952e+09 iat: 1.6409916e+09 integration_id: d4e5f6a1-b2c3-7890-1234-567890abcdef organization_id: 550e8400-e29b-41d4-a716-446655440000 scope: entities:write organizations:read sub: f47ac10b-58cc-4372-a567-0e02b2c3d479 token_type: Bearer user_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 username: user@picogrid.com "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/me: get: summary: Get current user description: Get the authenticated user's profile information. tags: - Me responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object patch: summary: Update current user description: Update the authenticated user's profile information. tags: - Me requestBody: required: true content: application/json: schema: example: email: john.doe.updated@example.com first_name: Johnny last_name: Doe Jr. properties: email: example: john.doe.updated@example.com format: email type: string first_name: example: Johnny type: string last_name: example: Doe Jr. type: string type: object example: email: john.doe.updated@example.com first_name: Johnny last_name: Doe Jr. responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/me/organization-invites: get: summary: Get my organization invitations description: Get all pending organization invitations for the authenticated user. tags: - Me parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: null previous: null properties: next: type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: accepted_at: example: "2024-03-12T09:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string created_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: new.member@example.com format: email type: string expires_at: example: "2024-03-17T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Example Innovations Inc. type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: FULL_ACCESS type: string token: example: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] type: string updated_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - organization_name - email - organization_role - expires_at - created_at - updated_at type: object type: array total_count: example: 1 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/me/orgs: get: summary: Get my organizations description: Get a paginated list of organizations the authenticated user belongs to. tags: - Me parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: null previous: null properties: next: type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: created_at: "2024-01-15T11:00:00Z" is_support: false organization_id: 550e8400-e29b-41d4-a716-446655440000 organization_name: Picogrid Corp organization_role: ADMIN updated_at: "2024-03-11T16:00:00Z" user_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 properties: created_at: example: "2024-01-15T11:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string is_support: example: false type: boolean organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Picogrid Corp type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: ADMIN type: string updated_at: example: "2024-03-11T16:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - organization_id - user_id - is_support - organization_name - organization_role - created_at - updated_at type: object type: array total_count: example: 2 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/me/webrtc/connections: delete: summary: Delete all WebRTC connections description: Delete all WebRTC websocket connection IDs for the currently authenticated user. tags: - WebRTC responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get all WebRTC connections description: Get all WebRTC websocket connection IDs for the currently authenticated user. tags: - WebRTC responses: "200": description: Successful response content: application/json: schema: items: properties: connection_id: example: conn_aBcDeFgHiJkLmNoPqRsT type: string session_id: example: G3jUFd4YoAMCFug= type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - connection_id - session_id type: object type: array "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create WebRTC connection description: Create a new WebRTC websocket connection ID for the currently authenticated user. tags: - WebRTC requestBody: required: true content: application/json: schema: example: connection_id: conn_zYxWvUtSrQpOnMlKjIhG session_id: H4kVEe5ZpBNDgXu= properties: connection_id: example: conn_zYxWvUtSrQpOnMlKjIhG type: string session_id: example: H4kVEe5ZpBNDgXu= type: string required: - session_id - connection_id type: object example: connection_id: conn_zYxWvUtSrQpOnMlKjIhG session_id: H4kVEe5ZpBNDgXu= responses: "201": description: Resource created successfully content: application/json: schema: properties: connection_id: example: conn_aBcDeFgHiJkLmNoPqRsT type: string session_id: example: G3jUFd4YoAMCFug= type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - connection_id - session_id type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/me/webrtc/connections/{sessionId}: delete: summary: Delete WebRTC connection description: Delete a specific WebRTC websocket connection ID for the currently authenticated user. tags: - WebRTC parameters: - name: sessionId in: path required: true schema: type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get WebRTC connection description: Get a specific WebRTC websocket connection ID for the currently authenticated user. tags: - WebRTC parameters: - name: sessionId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: properties: connection_id: example: conn_aBcDeFgHiJkLmNoPqRsT type: string session_id: example: G3jUFd4YoAMCFug= type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - connection_id - session_id type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/mesh/machines: get: summary: List all overlay machines for the current org description: Returns every active overlay machine in the organization — Legion machines and mesh-only workstations, each flagged with is_legion. Requires system admin; org is taken from X-ORG-ID. tags: - Mesh parameters: - name: limit in: query required: false schema: default: 100 maximum: 500 minimum: 1 type: number - name: offset in: query required: false schema: default: 0 minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: limit: type: number offset: type: number peers: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string is_legion: type: boolean lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at - is_legion type: object type: array total: type: number required: - peers - total - limit - offset type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Join a machine to the mesh description: 'Enrolls a workstation onto the overlay: short-lived Nebula cert scoped to the enrolling org''s group, inbound-deny firewall, no NATS artifacts. Requires system admin and a non-integration token; org is taken from X-ORG-ID.' tags: - Mesh requestBody: required: true content: application/json: schema: properties: hostname: type: string required: - hostname type: object responses: "201": description: Resource created successfully content: application/json: schema: properties: cert_not_after: type: string files: additionalProperties: type: string type: object hostname: type: string ip: type: string lighthouses: items: properties: endpoints: items: type: string type: array ip: type: string required: - ip - endpoints type: object type: array machine_id: format: uuid type: string required: - machine_id - hostname - ip - cert_not_after - files - lighthouses type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/mesh/machines/{id}: get: summary: Get a machine by ID description: Returns the machine's overlay entry (hostname, overlay IP, status, active cert metadata, is_legion). Requires system admin. tags: - Mesh parameters: - name: id in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string is_legion: type: boolean lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at - is_legion type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/mesh/machines/{id}/renew: post: summary: Renew a mesh-only machine's certificate description: 'Issues a fresh short-lived Nebula certificate for a mesh-only machine. Requires system admin, but system admin access alone is insufficient: only the identity that joined the machine may renew it, and any other caller (including another system admin) receives 403. Legion machines renew via /v3/federation and 404 here.' tags: - Mesh parameters: - name: id in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: cert_not_after: type: string files: additionalProperties: type: string type: object hostname: type: string ip: type: string lighthouses: items: properties: endpoints: items: type: string type: array ip: type: string required: - ip - endpoints type: object type: array machine_id: format: uuid type: string required: - machine_id - hostname - ip - cert_not_after - files - lighthouses type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/mesh/machines/{id}/revoke: post: summary: Revoke a mesh-only machine description: Marks a mesh-only machine revoked and revokes its certs. No roster event and no NATS deny-listing — the machine was never a federation participant. Legion machines are revoked via /v3/federation and 404 here. Requires system admin and a non-integration token. tags: - Mesh parameters: - name: id in: path required: true schema: format: uuid type: string requestBody: content: application/json: schema: properties: reason: type: string type: object responses: "200": description: Successful response content: application/json: schema: properties: machine_id: format: uuid type: string revoked_at: type: string status: type: string required: - machine_id - status - revoked_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/mesh/machines/all: get: summary: List overlay machines across all orgs description: Returns every overlay machine across all organizations — Legion machines and mesh-only workstations, each flagged with is_legion. Optional status and org-id filters. Requires system admin. tags: - Mesh parameters: - name: limit in: query required: false schema: default: 100 maximum: 500 minimum: 1 type: number - name: offset in: query required: false schema: default: 0 minimum: 0 type: number - name: org-id in: query required: false schema: format: uuid type: string - name: status in: query required: false schema: default: ACTIVE enum: - ACTIVE - REVOKED - all type: string responses: "200": description: Successful response content: application/json: schema: properties: limit: type: number offset: type: number peers: items: properties: cert_fingerprint: type: string cert_is_expired: type: boolean cert_not_after: type: string enrolled_at: type: string entity_id: format: uuid type: string hostname: type: string ip: type: string is_legion: type: boolean lan_subnet: type: string machine_id: format: uuid type: string organization_id: format: uuid type: string status: type: string required: - machine_id - organization_id - hostname - ip - cert_not_after - cert_is_expired - status - enrolled_at - is_legion type: object type: array total: type: number required: - peers - total - limit - offset type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications: get: summary: Get all notifications for an organization description: Retrieves all notifications of an organization. tags: - Notifications parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: created_at: type: string event: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object event_id: format: uuid type: string event_timestamp: example: "2023-12-15T14:30:00Z" type: string event_type: type: string id: format: uuid type: string metadata: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object organization_id: format: uuid type: string read_at: type: string subscription_id: format: uuid type: string required: - id - organization_id - event_id - subscription_id - event_timestamp - event_type - created_at type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/{notificationId}: get: summary: Get notification by ID description: Retrieves a specific notification by their ID. tags: - Notifications parameters: - name: notificationId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: type: string event: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object event_id: format: uuid type: string event_timestamp: example: "2023-12-15T14:30:00Z" type: string event_type: type: string id: format: uuid type: string metadata: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object organization_id: format: uuid type: string read_at: type: string subscription_id: format: uuid type: string required: - id - organization_id - event_id - subscription_id - event_timestamp - event_type - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/{notificationId}/channels/{eventSubscriptionChannelId}: get: summary: Get notification delivery by notfication ID and channel ID description: Retrieves a specific notification delivery by their notification ID and channel ID. tags: - Notifications parameters: - name: eventSubscriptionChannelId in: path required: true schema: format: uuid type: string - name: notificationId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: channel_id: format: uuid type: string created_at: example: "2023-12-15T14:30:00Z" type: string id: format: uuid type: string notification_id: format: uuid type: string sent_at: example: "2023-12-15T14:30:00Z" type: string status: example: "2023-12-15T14:30:00Z" type: string updated_at: example: "2023-12-15T14:30:00Z" type: string required: - id - notification_id - channel_id - status - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/{notificationId}/users/{userId}: get: summary: Get notification receipt by notification ID and user ID description: Retrieves a specific notification receipt by notification ID and user ID. tags: - Notifications parameters: - name: notificationId in: path required: true schema: format: uuid type: string - name: userId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2023-12-15T14:30:00Z" type: string id: format: uuid type: string notification_id: format: uuid type: string read_at: example: "2023-12-15T14:30:00Z" type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - notification_id - user_id - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update notification receipt description: Updates a notification receipt's information. tags: - Notifications parameters: - name: notificationId in: path required: true schema: format: uuid type: string - name: userId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: read_at: example: "2023-12-15T14:30:00Z" type: string type: object responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2023-12-15T14:30:00Z" type: string id: format: uuid type: string notification_id: format: uuid type: string read_at: example: "2023-12-15T14:30:00Z" type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - notification_id - user_id - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/deliveries/{notificationDeliveryId}: get: summary: Get notification delivery by ID description: Retrieves a specific notification delivery by their ID. tags: - Notifications parameters: - name: notificationDeliveryId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: channel_id: format: uuid type: string created_at: example: "2023-12-15T14:30:00Z" type: string id: format: uuid type: string notification_id: format: uuid type: string sent_at: example: "2023-12-15T14:30:00Z" type: string status: example: "2023-12-15T14:30:00Z" type: string updated_at: example: "2023-12-15T14:30:00Z" type: string required: - id - notification_id - channel_id - status - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/receipts/{notificationReceiptId}: get: summary: Get notification receipt by ID description: Retrieves a specific notification receipt by their ID. tags: - Notifications parameters: - name: notificationReceiptId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2023-12-15T14:30:00Z" type: string id: format: uuid type: string notification_id: format: uuid type: string read_at: example: "2023-12-15T14:30:00Z" type: string updated_at: example: "2023-12-15T14:30:00Z" type: string user_id: format: uuid type: string required: - id - notification_id - user_id - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/notifications/users/{userId}: get: summary: Get notification for a user description: Retrieves a user's notification within the current organization. tags: - Notifications parameters: - name: userId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: created_at: type: string event: properties: actor_id: format: uuid type: string actor_type: enum: - USER - ENTITY - OTHER example: ENTITY type: string created_at: type: string event_description: type: string event_timestamp: type: string event_type: enum: - HUMAN - VEHICLE - VESSEL - UAV - FOOTSTEP - ANIMAL - GUNSHOT - OTHER example: HUMAN type: string id: format: uuid type: string metadata: additionalProperties: true type: object organization_id: format: uuid type: string source_id: format: uuid type: string required: - id - organization_id - event_type - source_id - event_timestamp - created_at type: object event_id: format: uuid type: string event_timestamp: example: "2023-12-15T14:30:00Z" type: string event_type: type: string id: format: uuid type: string metadata: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object organization_id: format: uuid type: string read_at: type: string subscription_id: format: uuid type: string required: - id - organization_id - event_id - subscription_id - event_timestamp - event_type - created_at type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/openapi.json: get: summary: Get combined OpenAPI specification description: Returns the combined OpenAPI document for the Legion platform HTTP API, including this operation. The live document may list only the deployed server URL. tags: - Meta - Documentation responses: "200": description: OpenAPI 3.1 JSON document content: application/json: schema: description: OpenAPI 3.1 document describing this API (combined spec). type: object application/vnd.oai.openapi+json;version=3.1: schema: description: OpenAPI 3.1 document describing this API (combined spec). type: object headers: Cache-Control: description: Caching policy for this response. schema: type: string ETag: description: Entity tag for conditional requests (If-None-Match). schema: type: string "304": description: Not modified (If-None-Match matched the current document ETag). headers: Cache-Control: description: Caching policy for this response. schema: type: string ETag: description: Entity tag for conditional requests (If-None-Match). schema: type: string operationId: getV3OpenapiJson /v3/organization-invites/accept: post: summary: Accept organization invitation description: Accept an invitation to join an organization using the token received via email. tags: - Organization Invitations requestBody: required: true content: application/json: schema: example: token: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] properties: token: example: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] type: string required: - token type: object example: token: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] responses: "200": description: Successful response content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organization-invites/decline: post: summary: Decline organization invitation description: Decline an invitation to join an organization using the token received via email. tags: - Organization Invitations requestBody: required: true content: application/json: schema: example: token: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] properties: token: example: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] type: string required: - token type: object example: token: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] responses: "200": description: Successful response content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations: delete: summary: Delete organization description: Delete an organization and all associated data. Requires system admin permission only. tags: - Organizations responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get organization description: Get the current organization details. Requires org:viewer permission or system admin. tags: - Organizations responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2024-03-10T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string name: example: Picogrid Corp type: string updated_at: example: "2024-03-11T15:30:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - name - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object patch: summary: Update organization description: Update the current organization properties. Requires org:admin permission or system admin. tags: - Organizations requestBody: required: true content: application/json: schema: example: name: Picogrid Corp properties: name: example: Picogrid Corp type: string required: - name type: object example: name: Picogrid Corp responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2024-03-10T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string name: example: Picogrid Corp type: string updated_at: example: "2024-03-11T15:30:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - name - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create organization description: Create a new organization. Requires system admin permission. tags: - Organizations requestBody: required: true content: application/json: schema: example: name: Picogrid Corp properties: name: example: Picogrid Corp type: string required: - name type: object example: name: Picogrid Corp responses: "201": description: Resource created successfully content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2024-03-10T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string name: example: Picogrid Corp type: string updated_at: example: "2024-03-11T15:30:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - name - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations/all: get: summary: Get all organizations description: Get a paginated list of all organizations. Requires system admin permission. tags: - Organizations parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: created_at: "2023-12-15T14:30:00Z" id: 550e8400-e29b-41d4-a716-446655440000 name: Picogrid Corp updated_at: "2023-12-15T14:30:00Z" properties: created_at: example: "2024-03-10T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string name: example: Picogrid Corp type: string updated_at: example: "2024-03-11T15:30:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - name - created_at - updated_at type: object type: array total_count: example: 3 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations/invites: post: summary: Create organization invitation description: Send an invitation to a user to join the current organization. Requires organization ID in context and org:admin permission. tags: - Organization Invitations requestBody: required: true content: application/json: schema: example: email: new.member@example.com organization_role: FULL_ACCESS permissions: - {} - {} properties: email: example: new.member@example.com format: email type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: FULL_ACCESS type: string permissions: items: example: relation: viewer resource_id: 123e4567-e89b-12d3-a456-426614174000 resource_type: feed properties: relation: example: viewer type: string resource_id: example: 123e4567-e89b-12d3-a456-426614174000 pattern: ^(\*|[a-f0-9-]{36})$ type: string resource_type: example: feed type: string required: - resource_type - resource_id - relation type: object type: array required: - email - organization_role type: object example: email: new.member@example.com organization_role: FULL_ACCESS permissions: - {} - {} responses: "201": description: Resource created successfully content: application/json: schema: properties: accepted_at: example: "2024-03-12T09:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string created_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: new.member@example.com format: email type: string expires_at: example: "2024-03-17T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Example Innovations Inc. type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: FULL_ACCESS type: string token: example: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] type: string updated_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - organization_name - email - organization_role - expires_at - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations/invites/{inviteId}: delete: summary: Delete organization invitation description: Cancel a pending organization invitation. Requires organization ID in context and org:admin permission. tags: - Organization Invitations parameters: - name: inviteId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get organization invitation description: Get details of a specific organization invitation. Requires organization ID in context and org:viewer permission. tags: - Organization Invitations parameters: - name: inviteId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: accepted_at: example: "2024-03-12T09:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string created_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: new.member@example.com format: email type: string expires_at: example: "2024-03-17T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string id: format: uuid type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Example Innovations Inc. type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: FULL_ACCESS type: string token: example: eyJhbGciOiJIUzI1NiIsI[...]unique_token_part[...] type: string updated_at: example: "2024-03-10T10:05:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - organization_id - organization_name - email - organization_role - expires_at - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations/users: get: summary: Get all organization users description: Get a paginated list of users in the current organization. Requires organization ID in context and org:viewer permission. tags: - Organization Users parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: 0 properties: next: example: 2 type: - integer - "null" previous: example: 0 type: - integer - "null" required: - next - previous type: object results: items: properties: created_at: example: "2024-01-15T11:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string is_support: example: false type: boolean last_name: example: Doe type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Picogrid Corp type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: ADMIN type: string updated_at: example: "2024-03-11T16:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - is_support - organization_id - organization_role - created_at - updated_at type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/organizations/users/{userId}: delete: summary: Delete organization user description: Remove a user from the current organization. Requires organization ID in context and org:admin permission. tags: - Organization Users parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get organization user description: Get a specific user's membership details in the current organization. Requires organization ID in context and org:viewer permission. tags: - Organization Users parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string is_support: example: false type: boolean last_name: example: Doe type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Picogrid Corp type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: ADMIN type: string updated_at: example: "2024-03-11T16:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - is_support - organization_id - organization_role - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update organization user description: Update a user's role within the current organization. Requires organization ID in context and org:admin permission. tags: - Organization Users parameters: - name: userId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: organization_role: LIMITED properties: organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: LIMITED type: string required: - organization_role type: object example: organization_role: LIMITED responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string is_support: example: false type: boolean last_name: example: Doe type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string organization_name: example: Picogrid Corp type: string organization_role: enum: - ADMIN - FULL_ACCESS - LIMITED example: ADMIN type: string updated_at: example: "2024-03-11T16:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string required: - user_id - is_support - organization_id - organization_role - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/orgs/{organization_id}/ca-bundle: get: summary: Get the CA bundle for an org description: Returns the trusted CA certificate(s) the federation overlay uses to anchor Legion identity for the given org. Requires org:viewer. tags: - Federation parameters: - name: organization_id in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: ca_certs: items: type: string type: array required: - ca_certs type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/orion/release-notes/seen: get: summary: Get the authenticated user's last-seen release notes id description: Returns the opaque release-notes entry id the user last acknowledged. Null if never acknowledged. tags: - Orion responses: "200": description: "" content: application/json: schema: example: last_seen_release_notes_id: 2026-09-25-help-center properties: last_seen_release_notes_id: example: 2026-09-25-help-center type: - string - "null" required: - last_seen_release_notes_id type: object example: last_seen_release_notes_id: 2026-09-25-help-center "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Mark a release notes entry as seen for the authenticated user description: Persists the opaque release-notes entry id so the post-auth prompt stays dismissed across devices. tags: - Orion requestBody: required: true content: application/json: schema: example: last_seen_release_notes_id: 2026-09-25-help-center properties: last_seen_release_notes_id: example: 2026-09-25-help-center type: string required: - last_seen_release_notes_id type: object example: last_seen_release_notes_id: 2026-09-25-help-center responses: "200": description: Successful response content: application/json: schema: example: last_seen_release_notes_id: 2026-09-25-help-center properties: last_seen_release_notes_id: example: 2026-09-25-help-center type: - string - "null" required: - last_seen_release_notes_id type: object example: last_seen_release_notes_id: 2026-09-25-help-center "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/orion/settings: get: summary: Get a specific organization's orion settings description: Retrieves the orion settings for a specific organization tags: - Orion responses: "200": description: "" content: application/json: schema: properties: organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string viewport: example: bearing: 0 latitude: 38.871 longitude: -77.056 pitch: 0 zoom: 10 properties: bearing: maximum: 360 minimum: 0 type: number latitude: example: 38.871944 maximum: 90 minimum: -90 type: number longitude: example: -77.056389 maximum: 180 minimum: -180 type: number pitch: maximum: 60 minimum: 0 type: number zoom: example: "2023-12-15T14:30:00Z" maximum: 24 minimum: 0 type: number type: object required: - organization_id type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Creates or Updates a specific organization's orion settings description: Updates the orion settings for a specific organization. If the settings do not exist, they will be created. tags: - Orion requestBody: required: true content: application/json: schema: example: viewport: bearing: 0 latitude: 38.871 longitude: -77.056 pitch: 0 zoom: 10 properties: viewport: example: bearing: 0 latitude: 38.871 longitude: -77.056 pitch: 0 zoom: 10 properties: bearing: maximum: 360 minimum: 0 type: number latitude: example: 38.871944 maximum: 90 minimum: -90 type: number longitude: example: -77.056389 maximum: 180 minimum: -180 type: number pitch: maximum: 60 minimum: 0 type: number zoom: example: "2023-12-15T14:30:00Z" maximum: 24 minimum: 0 type: number type: object type: object example: viewport: bearing: 0 latitude: 38.871 longitude: -77.056 pitch: 0 zoom: 10 responses: "200": description: Successful response content: application/json: schema: properties: organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string viewport: example: bearing: 0 latitude: 38.871 longitude: -77.056 pitch: 0 zoom: 10 properties: bearing: maximum: 360 minimum: 0 type: number latitude: example: 38.871944 maximum: 90 minimum: -90 type: number longitude: example: -77.056389 maximum: 180 minimum: -180 type: number pitch: maximum: 60 minimum: 0 type: number zoom: example: "2023-12-15T14:30:00Z" maximum: 24 minimum: 0 type: number type: object required: - organization_id type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking: post: summary: Dispatch task description: Dispatches a task to the specified entity using the specified MQTT topic and payload. The command must have been registered in the system and the payload must match the schema for that command. tags: - Tasking requestBody: required: true content: application/json: schema: properties: command_name: example: Restart type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string payload: example: force: true reason: System maintenance timeout: 30 type: object qos: example: 1 maximum: 2 minimum: 0 type: number required: - entity_id - command_name - qos type: object responses: "200": description: Successful response content: application/json: schema: example: command_name: GetStatus dispatched_at: "2024-01-15T11:00:00Z" entity_id: f6a1b2c3-d4e5-7890-1234-567890abcdef task_id: c3d4e5f6-e7f8-9012-3456-789012cdef01 properties: command_name: example: GetStatus type: string dispatched_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: f6a1b2c3-d4e5-7890-1234-567890abcdef format: uuid type: string task_id: example: c3d4e5f6-e7f8-9012-3456-789012cdef01 format: uuid type: string required: - task_id - entity_id - command_name - dispatched_at type: object example: command_name: GetStatus dispatched_at: "2024-01-15T11:00:00Z" entity_id: f6a1b2c3-d4e5-7890-1234-567890abcdef task_id: c3d4e5f6-e7f8-9012-3456-789012cdef01 "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking/{taskId}: get: summary: Get task status description: Looks up the current status of the task using the task ID. tags: - Tasking parameters: - name: taskId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: command_name: example: Restart type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string payload: example: force: true reason: System maintenance timeout: 30 type: object status: enum: - SUCCESS - PENDING - FAILED - IN_PROGRESS - CANCELLED example: SUCCESS type: string task_id: example: a1b2e3f4-c5d6-7890-1234-567890abcdef format: uuid type: string timestamp: example: "2024-01-15T11:00:00Z" type: string required: - task_id - status - timestamp - command_name - entity_id type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking/entity/{entityId}/commands: delete: summary: Delete entity commands description: Deletes commands for the specified entity ID, by setting the commands field of the CommandsRegistration entry to an empty map. Note that this does not delete the CommandsRegistration entry itself, but only clears the commands field. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get entity commands description: Fetches all commands registered for the specified entity ID. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: commands: example: '{\"Restart\": {\"type\": \"object\", \"properties\": {\"delay\": {\"type\": \"integer\"}}}, \"Shutdown\": {\"type\": \"object\", \"properties\": {\"force\": {\"type\": \"boolean\"}}}}' type: object created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - commands - entity_id - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Register entity commands description: Registers commands for the specified entity. Merges with existing commands if they exist. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: commands: example: '{\"Restart\": {\"type\": \"object\", \"properties\": {\"delay\": {\"type\": \"integer\"}}}, \"Shutdown\": {\"type\": \"object\", \"properties\": {\"force\": {\"type\": \"boolean\"}}}}' type: object entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - commands - entity_id type: object responses: "201": description: Resource created successfully content: application/json: schema: properties: commands: example: '{\"Restart\": {\"type\": \"object\", \"properties\": {\"delay\": {\"type\": \"integer\"}}}, \"Shutdown\": {\"type\": \"object\", \"properties\": {\"force\": {\"type\": \"boolean\"}}}}' type: object created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - commands - entity_id - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update entity commands description: Updates commands for the specified entity ID. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: commands: example: '{\"Restart\": {\"type\": \"object\", \"properties\": {\"delay\": {\"type\": \"integer\"}}}, \"Shutdown\": {\"type\": \"object\", \"properties\": {\"force\": {\"type\": \"boolean\"}}}}' type: object required: - commands type: object responses: "200": description: Successful response content: application/json: schema: properties: commands: example: '{\"Restart\": {\"type\": \"object\", \"properties\": {\"delay\": {\"type\": \"integer\"}}}, \"Shutdown\": {\"type\": \"object\", \"properties\": {\"force\": {\"type\": \"boolean\"}}}}' type: object created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - commands - entity_id - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking/entity/{entityId}/mqtt-topic: delete: summary: Delete MQTT topic description: Deletes MQTT topics for the specified entity ID and command name. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: commandName in: query required: true schema: pattern: ^[A-Za-z0-9._-]{1,128}$ type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Register MQTT topics for one command or many (legacy URL) description: Registers one command's MQTT topic pair for the specified entity ID. Legacy alias of POST /v3/tasking/entity/{entityId}/mqtt-topics, kept because deployed clients have this URL baked in; the request is processed as a batch of one through the same implementation. New callers should use the unified endpoint. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: oneOf: - properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string required: - entity_id - command_name - request_mqtt_topic - response_mqtt_topic type: object - properties: entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string topics: additionalProperties: properties: request_mqtt_topic: pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string required: - request_mqtt_topic - response_mqtt_topic type: object example: reboot: request_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/reboot response_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/reboot restart: request_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart response_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart type: object required: - entity_id - topics type: object responses: "201": description: Resource created successfully content: application/json: schema: oneOf: - properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object - properties: results: items: properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object type: array total_count: example: 16 type: integer required: - results - total_count type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update MQTT topic description: Updates MQTT topics for the specified entity ID and command name. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: commandName in: query required: true schema: pattern: ^[A-Za-z0-9._-]{1,128}$ type: string requestBody: required: true content: application/json: schema: properties: command_name: example: reboot pattern: ^[A-Za-z0-9._-]{1,128}$ type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/reboot pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/reboot pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string required: - command_name - request_mqtt_topic - response_mqtt_topic type: object responses: "200": description: Successful response content: application/json: schema: properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking/entity/{entityId}/mqtt-topics: get: summary: Get MQTT topics description: Fetches the MQTT topics registered for the specified entity ID and command name. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: commandName in: query required: true schema: pattern: ^[A-Za-z0-9._-]{1,128}$ type: string responses: "200": description: Successful response content: application/json: schema: properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Register MQTT topics for one command or many description: Registers the request/response MQTT topic pair for commands on the specified entity. Accepts either the legacy single-command form or the bulk map form on one URL; the response mirrors whichever form arrived (the flat topic object for the single form, the results envelope for the bulk form). Registering N commands one at a time costs N requests; the bulk form costs one. Existing topics for a command name are updated, so the call is idempotent and safe to retry. In the bulk form, either every topic pair is written or none is. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: oneOf: - properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string required: - entity_id - command_name - request_mqtt_topic - response_mqtt_topic type: object - properties: entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string topics: additionalProperties: properties: request_mqtt_topic: pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string required: - request_mqtt_topic - response_mqtt_topic type: object example: reboot: request_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/reboot response_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/reboot restart: request_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart response_mqtt_topic: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart type: object required: - entity_id - topics type: object responses: "201": description: Resource created successfully content: application/json: schema: oneOf: - properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object - properties: results: items: properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object type: array total_count: example: 16 type: integer required: - results - total_count type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tasking/entity/{entityId}/mqtt-topics/all: get: summary: Get all MQTT topics description: Fetches all MQTT topics registered for the specified entity ID. tags: - Tasking parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: command_name: example: restart pattern: ^[A-Za-z0-9._-]{1,128}$ type: string created_at: example: "2023-01-01T10:00:00Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string id: format: uuid type: string request_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/request/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string response_mqtt_topic: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f/task/response/aws/restart pattern: ^[A-Za-z0-9._:/-]{1,512}$ type: string updated_at: example: "2023-01-15T15:30:45Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - id - entity_id - command_name - request_mqtt_topic - response_mqtt_topic - created_at - updated_at type: object type: array total_count: example: 5 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks: post: summary: Create track description: Creates a new track tags: - Tracks parameters: - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: example: metadata: capabilities: - video - thermal manufacturer: DJI model: Mavic 3 name: Drone-1 parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: active type: UAV properties: affiliation: example: "2023-12-15T14:30:00Z" type: string metadata: example: capabilities: - video - thermal manufacturer: DJI model: Mavic 3 type: object name: example: Drone-1 type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: string status: example: active type: string type: example: UAV type: string required: - name - type - status type: object example: metadata: capabilities: - video - thermal manufacturer: DJI model: Mavic 3 name: Drone-1 parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: active type: UAV responses: "201": description: Created content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks/{trackId}: delete: summary: Delete track description: Deletes a track and associated data tags: - Tracks parameters: - name: trackId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get track by ID description: Retrieves a specific track by ID tags: - Tracks parameters: - name: trackId in: path required: true schema: format: uuid type: string - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean responses: "200": description: Successful response content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update track description: Updates a track's information tags: - Tracks parameters: - name: trackId in: path required: true schema: format: uuid type: string - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: example: metadata: capabilities: - video manufacturer: Parrot model: Anafi name: Drone-2 parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: inactive type: Fixed-Wing properties: affiliation: example: "2023-12-15T14:30:00Z" type: string metadata: example: capabilities: - video manufacturer: Parrot model: Anafi type: object name: example: Drone-2 type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: string status: example: inactive type: string type: example: Fixed-Wing type: string type: object example: metadata: capabilities: - video manufacturer: Parrot model: Anafi name: Drone-2 parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: inactive type: Fixed-Wing responses: "200": description: Successful response content: application/json: schema: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks/{trackId}/locations: get: summary: Get track locations description: Get historical locations for a track tags: - Track Locations parameters: - name: trackId in: path required: true schema: format: uuid type: string - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string paging: example: has_more: true next: 2 previous: null properties: has_more: example: true type: boolean next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: integer required: - results - paging - crs type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create track location description: Creates a new location for a track tags: - Track Locations parameters: - name: trackId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 1 - 0 - 0 items: type: number type: array type: array crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2023-10-01T12:00:00Z" type: string source: example: Helios type: string velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - position - source type: object responses: "201": description: Created content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks/{trackId}/locations/{trackLocationId}: get: summary: Get track location description: Get a specific location for a track tags: - Track Locations parameters: - name: trackId in: path required: true schema: format: uuid type: string - name: trackLocationId in: path required: true schema: format: uuid type: string - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string responses: "200": description: Successful response content: application/json: schema: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks/locations/search: post: summary: Search track locations description: Search track locations with complex filtering and pagination tags: - Track Locations parameters: - name: crs in: query required: false schema: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string filters: properties: categories: example: - DEVICE - SENSOR items: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK type: string type: array created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string entity_ids: example: - c3d4e5f6-a1b2-7890-1234-567890abcdef - f6a1b2c3-d4e5-7890-1234-567890abcdef items: format: uuid type: string type: array proximity_filter: example: position: - 4.51759087e+06 - 0 - 4.48734841e+06 radius: 250 properties: crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string position: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array radius: example: 250 type: number required: - position - radius type: object recorded_after: example: "2024-01-01T00:00:00Z" type: string recorded_before: example: "2024-12-31T23:59:59Z" type: string sources: example: - Helios - KALMAN_FILTER items: type: string type: array type: object hydrate_entities: example: true type: boolean latest_only: example: true type: boolean sort: items: example: field: created_at order: desc properties: field: enum: - id - entity_id - position - orientation - recorded_at - created_at - velocity - angular_velocity example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string paging: example: has_more: true next: 2 previous: null properties: has_more: example: true type: boolean next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean metadata: example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - affiliation - status - parent_id - created_at - updated_at type: object entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: integer required: - results - paging - crs type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/tracks/search: post: summary: Search tracks description: Search tracks with complex filtering and pagination tags: - Tracks parameters: - name: include_classification_vector in: query required: false schema: default: false type: boolean - name: limit in: query required: false schema: default: 10 example: 10 maximum: 1000 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer - name: with_location_latest in: query required: false schema: default: false type: boolean requestBody: required: true content: application/json: schema: properties: filters: properties: affiliation: example: - FRIEND - NEUTRAL items: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED type: string type: array category: example: - DEVICE - SENSOR items: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK type: string type: array created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string entity_ids: example: - c3d4e5f6-a1b2-7890-1234-567890abcdef - e5f6a1b2-c3d4-7890-1234-567890abcdef items: format: uuid type: string type: array expires_after: example: "2025-01-01T00:00:00Z" type: string expires_before: example: "2026-12-31T23:59:59Z" type: string is_active: example: true type: boolean name: example: Camera type: string parent_ids: example: - a1b2c3d4-e5f6-7890-1234-567890abcdef items: format: uuid type: string type: array status: items: type: string type: array top_classifications: example: - HUMAN - VEHICLE items: type: string type: array types: example: - Camera - Environmental items: type: string type: array updated_after: example: "2024-02-01T00:00:00Z" type: string updated_before: example: "2024-03-31T23:59:59Z" type: string type: object sort: items: example: field: created_at order: desc properties: field: enum: - name - status - type - category - affiliation - organization_id - created_at - updated_at - expires_at - is_active - id - top_classification - recorded_at - position - orientation - entity_id - parent_id example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array with_location_latest: example: false type: boolean type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: example: affiliation: FRIEND category: DEVICE created_at: "2023-12-15T14:30:00Z" id: 123e4567-e89b-12d3-a456-426614174000 metadata: manufacturer: General Atomics model: MQ-9 name: MQ-9 Reaper organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: 456e8400-e29b-41d4-a716-446655440000 status: ACTIVE type: DRONE updated_at: "2023-12-15T14:30:00Z" properties: affiliation: enum: - PENDING - UNKNOWN - ASSUMED_FRIEND - FRIEND - NEUTRAL - SUSPECT - HOSTILE - EXERCISE_PENDING - EXERCISE_UNKNOWN - EXERCISE_FRIEND - EXERCISE_NEUTRAL - EXERCISE_ASSUMED_FRIEND - JOKER - FAKER - NONE_SPECIFIED example: FRIEND type: string category: enum: - DEVICE - DETECTION - ALERT - WEATHER - GEOMETRIC - ZONE - SENSOR - VEHICLE - UXV - TRACK example: DEVICE type: string classification: additionalProperties: true example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string expires_at: example: "2029-12-31T23:59:59Z" type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string is_active: example: true type: boolean is_expired: example: false type: boolean location_latest: properties: acceleration: example: - 0 - 0.01 - -0.02 items: type: number type: array angular_velocity: example: - 0 - 0.01 - -0.02 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - - 25 - 0 - 0 - - 0 - 25 - 0 - - 0 - 0 - 9 items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: default: EPSG:4978 enum: - EPSG:4978 - EPSG:4326 - EPSG:4979 example: EPSG:4978 type: string entity_id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string id: example: 10c98fcd-e351-4a2d-7af1-29876543210a format: uuid type: string orientation: example: - 0.707 - 0 - 0 - 0.707 items: type: number maxItems: 4 minItems: 4 type: array position: example: coordinates: - 4.51759087e+06 - 0 - 4.48734841e+06 type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number type: array type: example: Point pattern: ^(Point|LineString|Polygon)$ type: string required: - type - coordinates type: object radius: example: 500 type: number recorded_at: example: "2024-01-15T11:00:00Z" type: string source: example: Helios type: string speed: example: 2.236 type: number velocity: example: - 42.5 - -3.1 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object metadata: additionalProperties: true example: ip_address: 192.168.1.150 manufacturer: Axis Communications model: P1448-LE night_vision: true pan_tilt: true resolution: 4K weatherproof: true zoom_range: 12x optical type: object name: example: Axis IP Camera type: string organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string parent_id: example: a1b2c3d4-e5f6-7890-1234-567890abcdef format: uuid type: - string - "null" status: example: active type: string top_classification: example: HUMAN type: string top_classification_probability: example: 0.95 type: number type: example: Camera type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - name - category - type - status - affiliation - parent_id - created_at - updated_at - is_expired type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/users: get: summary: Get all users description: Get a paginated list of all users. Requires system admin permission. tags: - Users parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 50 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: example: - created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD items: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object type: array total_count: example: 25 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Create admin user description: Create a new user. Requires org:admin permission (permission-first with scope fallback). tags: - Users requestBody: required: true content: application/json: schema: example: email: jane.doe@example.com first_name: Jane last_name: Doe properties: email: example: jane.doe@example.com format: email type: string first_name: example: Jane type: string last_name: example: Doe type: string required: - email - first_name - last_name type: object example: email: jane.doe@example.com first_name: Jane last_name: Doe responses: "201": description: Resource created successfully content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/users/{userId}: delete: summary: Delete user description: Delete a user and their data. Requires system admin permission. Self-deletion is not permitted. tags: - Users parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get user by ID description: Get a specific user by their ID. Requires system admin permissions. tags: - Users parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object put: summary: Update user description: Update user info. Requires system admin permission or self-modification (users can update their own profile). tags: - Users parameters: - name: userId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: email: john.doe.updated@example.com first_name: Johnny last_name: Doe Jr. properties: email: example: john.doe.updated@example.com format: email type: string first_name: example: Johnny type: string last_name: example: Doe Jr. type: string type: object example: email: john.doe.updated@example.com first_name: Johnny last_name: Doe Jr. responses: "200": description: Successful response content: application/json: schema: example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD properties: created_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string email: example: user@picogrid.com format: email type: string first_name: example: John type: string id: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string last_name: example: Doe type: string updated_at: example: "2024-02-16T21:45:33Z" pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string user_role: example: STANDARD pattern: ^(STANDARD|GLOBAL_ADMIN)$ type: string required: - id - email - first_name - last_name - user_role - created_at - updated_at type: object example: created_at: "2023-12-15T14:30:00Z" email: user@picogrid.com first_name: John id: f47ac10b-58cc-4372-a567-0e02b2c3d479 last_name: Doe updated_at: "2023-12-15T14:30:00Z" user_role: STANDARD "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/users/{userId}/system-admin: delete: summary: Revoke system admin permission description: Revoke system admin permission from a user. Requires the requesting user to be a system admin. Self-revocation is not permitted. tags: - Users parameters: - name: userId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: example: message: System admin permission revoked successfully success: true properties: message: example: System admin permission revoked successfully type: string success: example: true type: boolean required: - success - message type: object example: message: System admin permission revoked successfully success: true "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Grant system admin permission description: Grant system admin permission to a user. Requires the requesting user to already be a system admin. tags: - Users parameters: - name: userId in: path required: true schema: format: uuid type: string requestBody: content: application/json: schema: example: reason: Promoted to platform administrator properties: reason: example: Promoted to platform administrator type: string type: object example: reason: Promoted to platform administrator responses: "200": description: Successful response content: application/json: schema: example: message: System admin permission granted successfully success: true properties: message: example: System admin permission granted successfully type: string success: example: true type: boolean required: - success - message type: object example: message: System admin permission granted successfully success: true "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video: post: summary: Create video stream description: Creates a new video stream associated with an entity tags: - Video Streams requestBody: required: true content: application/json: schema: example: entity_id: d4e5f6a1-b2c3-7890-1234-567890abcdef metadata: camera_type: PTZ frame_rate: 30 night_vision: true resolution: 1920x1080 protocol: RTMP stream_name: drone_primary_feed properties: entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true resolution: 1920x1080 type: object protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string stream_name: example: drone_primary_feed type: string required: - entity_id - stream_name - protocol type: object example: entity_id: d4e5f6a1-b2c3-7890-1234-567890abcdef metadata: camera_type: PTZ frame_rate: 30 night_vision: true resolution: 1920x1080 protocol: RTMP stream_name: drone_primary_feed responses: "200": description: Idempotent response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string id: format: uuid type: string is_active: example: true type: boolean metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true zoom_level: 10x type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string playback_endpoints: additionalProperties: type: string type: object playback_url: type: string protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string publish_url: type: string stream_name: example: drone_primary_feed type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at type: object "201": description: Created content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string id: format: uuid type: string is_active: example: true type: boolean metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true zoom_level: 10x type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string playback_endpoints: additionalProperties: type: string type: object playback_url: type: string protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string publish_url: type: string stream_name: example: drone_primary_feed type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "409": description: Conflict content: application/json: schema: properties: category: type: string code: example: 409 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request conflicts with current state of the resource type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "422": description: Unprocessable Entity content: application/json: schema: properties: category: type: string code: example: 422 type: number details: items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request data is well-formed but violates business rules type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}: delete: summary: Delete all video streams for entity description: Deletes all video stream configurations associated with a specific entity tags: - Video Streams parameters: - name: entityId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: deleted_count: example: 3 type: number message: example: Successfully deleted streams for entity type: string required: - deleted_count - message type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get video streams for entity description: Retrieves all video stream configurations associated with a specific entity tags: - Video Streams parameters: - name: entityId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: streams: items: properties: created_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string id: format: uuid type: string is_active: example: true type: boolean metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true zoom_level: 10x type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string playback_endpoints: additionalProperties: type: string type: object playback_url: type: string protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string publish_url: type: string stream_name: example: drone_primary_feed type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at type: object type: array required: - streams type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}: delete: summary: Delete specific video stream description: Deletes a specific video stream configuration by its ID tags: - Video Streams parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string responses: "204": description: No content "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object get: summary: Get specific video stream description: Retrieves a specific video stream configuration by its ID tags: - Video Streams parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string responses: "200": description: Successful response content: application/json: schema: properties: created_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string id: format: uuid type: string is_active: example: true type: boolean metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true zoom_level: 10x type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string playback_endpoints: additionalProperties: type: string type: object playback_url: type: string protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string publish_url: type: string stream_name: example: drone_primary_feed type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}/recordings/download: get: summary: Download recordings via signed URL description: 'Streams a single MP4 (Content-Disposition: attachment) for the signed time range. Authenticated by the sig query parameter minted by the POST method on this path — no Authorization header — so browser navigations and download managers work directly.' tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string - name: end in: query required: true schema: type: string - name: expires in: query required: true schema: example: "1769000060" type: string - name: org in: query required: true schema: format: uuid type: string - name: sig in: query required: true schema: example: hkQx2Vv9pTzXcW1sYtR8uAqBdEfGhIjKlMnOpQrStUv type: string - name: start in: query required: true schema: type: string responses: "200": description: Concatenated MP4 download (video/mp4) content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object post: summary: Mint signed recordings download URL description: Returns a short-lived signed URL (GET on this same path) that downloads the requested time range as a single MP4 without an Authorization header, for browser-native downloads. Authorization is checked here; the URL is a capability scoped to this stream and range until it expires. The requested time range must be greater than zero and must not exceed DVR_MAX_DOWNLOAD_RANGE, which defaults to 1 hour. tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: time_range: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" properties: time_range: example: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" properties: end: type: string start: type: string required: - start - end type: object required: - time_range type: object example: time_range: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" responses: "200": description: Signed download URL content: application/json: schema: properties: expires_at: example: "2026-01-01T00:01:00Z" type: string url: example: /v3/video/6a4c.../9f2e.../recordings/download?start=2026-01-01T00%3A00%3A00Z&end=2026-01-01T00%3A10%3A00Z&org=1b7d...&expires=1769000060&sig=hkQ... type: string required: - url - expires_at type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}/recordings/playlist.m3u8: get: summary: Get recordings HLS playlist description: Returns an HLS VOD playlist (application/vnd.apple.mpegurl) covering the recordings that overlap the optional start/end window tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string - name: end in: query required: false schema: type: string - name: start in: query required: false schema: type: string responses: "200": description: HLS playlist (application/vnd.apple.mpegurl) content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}/recordings/search: post: summary: Search recordings description: Search DVR recordings of a video stream with an optional time window and cursor pagination tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: streamId in: path required: true schema: format: uuid type: string requestBody: required: true content: application/json: schema: example: limit: 100 time_range: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" properties: cursor: example: MTcwNDA2NzIwMDAwMDAwMHw3ZDI0... type: string limit: example: 100 maximum: 1000 minimum: 1 type: integer time_range: example: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" properties: end: type: string start: type: string type: object type: object example: limit: 100 time_range: end: "2026-01-01T01:00:00Z" start: "2026-01-01T00:00:00Z" responses: "200": description: Successful response content: application/json: schema: properties: next_cursor: example: MTcwNDA2NzIwMDAwMDAwMHw3ZDI0... type: string recordings: items: properties: duration_seconds: example: 60 type: number format: example: fmp4 type: string id: example: bWVkaWFtdHgvb3JnL2VudGl0eS9zdHJlYW0vMjAyNi8wMS8wMS8wMC0wMC0wMC0wMDAwMDAubXA0 type: string size_bytes: example: 1.048576e+06 type: integer start_time: example: "2026-01-01T00:00:00Z" type: string required: - id - start_time - duration_seconds - size_bytes - format type: object type: array required: - recordings type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}/recordings/segments/{recordingId}: get: summary: Get recording segment description: Streams the bytes of a single fMP4 recording segment identified by its opaque recording ID tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: recordingId in: path required: true schema: example: bWVkaWFtdHgvb3JnL2VudGl0eS9zdHJlYW0vMjAyNi8wMS8wMS8wMC0wMC0wMC0wMDAwMDAubXA0 pattern: ^[A-Za-z0-9_-]{1,512}$ type: string - name: streamId in: path required: true schema: format: uuid type: string responses: "200": description: Recording segment bytes (video/mp4) content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/{entityId}/{streamId}/recordings/segments/{recordingId}/init: get: summary: Get recording segment init section description: Returns just the ftyp+moov initialization bytes of a recording segment; HLS playlists reference this as each segment's EXT-X-MAP URI tags: - Video Recordings parameters: - name: entityId in: path required: true schema: format: uuid type: string - name: recordingId in: path required: true schema: example: bWVkaWFtdHgvb3JnL2VudGl0eS9zdHJlYW0vMjAyNi8wMS8wMS8wMC0wMC0wMC0wMDAwMDAubXA0 pattern: ^[A-Za-z0-9_-]{1,512}$ type: string - name: streamId in: path required: true schema: format: uuid type: string responses: "200": description: Recording segment initialization bytes (video/mp4) content: application/json: schema: description: Reference to nil type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object /v3/video/search: post: summary: Search video streams description: Search for video streams within an organization using various filters. System admins may search any organization by supplying its ID in the org context header. tags: - Video Streams parameters: - name: limit in: query required: false schema: default: 10 example: 10 maximum: 100 minimum: 1 type: integer - name: offset in: query required: false schema: default: 0 example: 0 minimum: 0 type: integer requestBody: required: true content: application/json: schema: properties: filters: properties: entity_ids: items: format: uuid type: string type: array is_active: type: boolean protocols: items: type: string type: array type: object sort: items: properties: field: enum: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at example: created_at type: string order: enum: - asc - desc example: desc type: string required: - field - order type: object type: array type: object responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - integer - "null" previous: type: - integer - "null" required: - next - previous type: object results: items: properties: created_at: example: "2024-01-15T11:00:00Z" type: string entity_id: example: d4e5f6a1-b2c3-7890-1234-567890abcdef format: uuid type: string id: format: uuid type: string is_active: example: true type: boolean metadata: example: camera_type: PTZ frame_rate: 30 night_vision: true zoom_level: 10x type: object organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string playback_endpoints: additionalProperties: type: string type: object playback_url: type: string protocol: enum: - rtsp - rtmp - hls - webrtc - srt example: RTMP type: string publish_url: type: string stream_name: example: drone_primary_feed type: string updated_at: example: "2024-03-11T16:00:00Z" type: string required: - id - organization_id - entity_id - stream_name - protocol - is_active - created_at - updated_at type: object type: array total_count: example: 8 type: integer required: - results - total_count - paging type: object "400": description: Bad Request content: application/json: schema: properties: category: type: string code: example: 400 type: number details: example: - Field: organization_id Issue: must be a valid UUID format items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Request cannot be processed due to invalid input type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "401": description: Unauthorized content: application/json: schema: properties: category: type: string code: example: 401 type: number details: example: - Field: authorization_header Issue: Bearer token is expired or malformed items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: Authentication credentials are missing or invalid type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "403": description: Forbidden content: application/json: schema: properties: category: type: string code: example: 403 type: number details: example: - Field: required_scope Issue: requires 'orion:settings:write' scope, but token only has 'orion:settings:read' items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: 'Access denied: insufficient permissions for this resource' type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "404": description: Not Found content: application/json: schema: properties: category: type: string code: example: 404 type: number details: example: - Field: organization_id Issue: organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found items: properties: field: example: email type: string issue: example: must be a valid email address type: string required: - field - issue type: object type: array message: example: The requested resource could not be found type: string status: example: error type: string timestamp: example: "2026-01-15T14:32:45Z" type: string trace_id: example: req_2J9K8L7M6N5P4Q3R type: string required: - status - code - message - category - timestamp - trace_id type: object "500": description: Internal Server Error content: application/json: schema: properties: category: description: The category of the error example: server_error type: string code: description: The HTTP status code example: 500 type: number details: description: Additional details about the error items: properties: field: description: The field that caused the error example: field_name type: string issue: description: The specific issue with the field example: Field validation issue type: string type: object type: array message: description: A human-readable error message example: Internal Server Error type: string status: description: The status of the response, always 'error' for error responses example: error type: string timestamp: description: The timestamp when the error occurred example: "2024-03-15T10:30:00Z" format: date-time type: string trace_id: description: A unique identifier for tracing the error example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string required: - status - code - message - category - timestamp - trace_id type: object components: securitySchemes: Bearer: type: http description: JWT token for authentication scheme: bearer bearerFormat: JWT oauth2: type: oauth2 description: OAuth 2.0 authentication with JWT tokens for Legion Platform integration access flows: authorizationCode: authorizationUrl: /v3/integrations/oauth/authorize tokenUrl: /v3/integrations/oauth/token refreshUrl: /v3/integrations/oauth/revoke scopes: entities:read: Read entity information entities:write: Create, update, and delete entity information feeds:read: Read feed data and definitions feeds:write: Write feed data and manage feed definitions integrations:manage: Manage integrations integrations:read: Read integration configurations organizations:create: Create new organizations organizations:delete: Delete organizations organizations:read: Read organization information organizations:read:all: Read all organizations organizations:users:read: Read organization users organizations:users:write: Modify organization users organizations:write: Modify organization settings tasking:read: Read tasking information tasking:write: Create, update, manage, and execute tasking commands users:read: Read all users from all organizations users:write: Write all users from all organizations