openapi: 3.1.0 info: title: Legion Platform API version: 3.0.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/auth/mediamtx: post: summary: MediaMTX Authentication description: Authenticates MediaMTX streaming requests using JWT tokens tags: - Auth requestBody: required: true content: application/json: schema: example: action: publish id: test-id ip: 192.168.1.100 password: "" path: orgId/entityId/streamName protocol: rtsp query: ?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... user: testuser properties: action: example: publish type: string id: example: test-id type: string ip: example: 192.168.1.100 type: string password: example: "" type: string path: example: orgId/entityId/streamName type: string protocol: example: rtsp type: string query: example: ?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... type: string token: example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... type: string user: example: testuser type: string type: object example: action: publish id: test-id ip: 192.168.1.100 password: "" path: orgId/entityId/streamName protocol: rtsp query: ?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... user: testuser 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/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: resource_type in: query required: false schema: example: entity type: string - name: resource_id in: query required: false schema: example: 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string - name: start_date in: query required: false schema: example: "2024-01-16T21:45:33Z" type: string - name: subject_type in: query required: false schema: example: user type: string - name: limit in: query required: false schema: example: 50 maximum: 100 minimum: 1 type: number - name: subject_id in: query required: false schema: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 format: uuid type: string - 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: offset in: query required: false schema: example: 0 minimum: 0 type: number 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: number 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: number 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 "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 "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: number reason: example: Direct permission granted type: string required: - index - allowed - reason - from_cache type: object type: array total_count: example: 1 type: number 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 "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: number offset: example: 0 minimum: 0 type: number 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: number 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: number 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: number 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 "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: number 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 "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: number 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 "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: number 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 "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: number offset: example: 0 minimum: 0 type: number 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: number has_more: example: true type: boolean offset: example: 0 type: number 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: number 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 "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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 50 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: has_more: example: false type: boolean limit: example: 50 type: number offset: example: 0 type: number 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: number 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 "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 "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 "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: number 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 "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: number 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 "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 requestBody: required: true content: application/json: schema: example: affiliation: FRIEND category: DEVICE 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 organization_id: 550e8400-e29b-41d4-a716-446655440000 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: example: "2023-12-15T14:30:00Z" type: object 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 required: - organization_id - name - category - type - status type: object example: affiliation: FRIEND category: DEVICE 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 organization_id: 550e8400-e29b-41d4-a716-446655440000 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: example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 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 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: example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 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 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: 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: example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 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 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 requestBody: required: true content: application/json: schema: example: affiliation: NEUTRAL category: SENSOR 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: example: "2023-12-15T14:30:00Z" type: object metadata: 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 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: example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 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 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/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: offset in: query required: false schema: minimum: 0 type: number - name: crs in: query required: false schema: enum: - EPSG:4978 - EPSG:4326 example: EPSG:4978 type: string - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 example: EPSG:4978 type: string paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 items: type: number type: array angular_velocity: example: - 0 - 0.01 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - {} - {} - {} items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: enum: - EPSG:4978 - EPSG:4326 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: number required: - results - total_count - 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 items: type: number type: array angular_velocity: example: - 0 - 0.01 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - {} - {} - {} items: example: - 1 - 0 - 0 items: type: number type: array type: array crs: enum: - EPSG:4978 - EPSG:4326 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 - 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 items: type: number type: array angular_velocity: example: - 0 - 0.01 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - {} - {} - {} items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: enum: - EPSG:4978 - EPSG:4326 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - 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: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number - name: crs in: query required: false schema: enum: - EPSG:4978 - EPSG:4326 example: EPSG:4978 type: string responses: "200": description: Successful response content: application/json: schema: properties: acceleration: example: - 0 - 0.01 items: type: number type: array angular_velocity: example: - 0 - 0.01 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - {} - {} - {} items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: enum: - EPSG:4978 - EPSG:4326 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - 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/locations/search: post: summary: Search entity locations description: Search entity locations with complex filtering and pagination tags: - Entity Locations parameters: - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number - name: crs in: query required: false schema: enum: - EPSG:4978 - EPSG:4326 example: EPSG:4978 type: string requestBody: required: true content: application/json: schema: properties: crs: enum: - EPSG:4978 - EPSG:4326 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: enum: - EPSG:4978 - EPSG:4326 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: 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 example: EPSG:4978 type: string paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "null" required: - next - previous type: object results: items: properties: acceleration: example: - 0 - 0.01 items: type: number type: array angular_velocity: example: - 0 - 0.01 items: type: number type: array bearing: example: 45 maximum: 360 minimum: 0 type: number covariance: example: - {} - {} - {} items: example: - 25 - 0 - 0 items: type: number type: array type: array created_at: example: "2024-01-15T11:00:00Z" type: string crs: enum: - EPSG:4978 - EPSG:4326 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - 0 items: type: number type: array required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: number required: - results - total_count - 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/search: post: summary: Search entities description: Search entities with complex filtering and pagination tags: - Entities parameters: - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number - name: include_classification_vector in: query required: false schema: 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 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: 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: - number - "null" previous: type: - number - "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: example: "2023-12-15T14:30:00Z" type: object created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 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 type: object type: array total_count: example: 25 type: number 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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number 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: - number - "null" previous: type: - number - "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: number 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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: 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: number 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: 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: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number 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: 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: - number - "null" previous: type: - number - "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: 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: number 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/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/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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 100 minimum: 1 type: number 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: - number - "null" previous: type: - number - "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: number 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: maximum: 100 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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: maximum: 100 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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: maximum: 100 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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 should contain a ''metadata_json_payload'' field with JSON metadata matching the IngestFeedFileDataRequest schema, and a ''file'' field with the binary file content. Note: This endpoint uses multipart/form-data, not application/json as shown in the schema below.' tags: - Feed Data requestBody: required: true content: application/json: schema: 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 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 "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: abc123-def456-ghi789.jpg 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: maximum: 100 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number 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 created_after: example: "2024-01-01T00:00:00Z" type: string created_before: example: "2024-12-31T23:59:59Z" type: string 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 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: - number - "null" previous: type: - number - "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: number 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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 50 minimum: 1 type: number 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 type: string grant_type: 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_type_hint in: query required: false schema: example: access_token type: string - name: token in: query required: true schema: example: jwt_access_token_example_placeholder 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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 50 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: null previous: null properties: next: type: - number - "null" previous: type: - number - "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: number 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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: null previous: null properties: next: type: - number - "null" previous: type: - number - "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: number 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/notifications: get: summary: Get all notifications for an organization description: Retrieves all notifications of an organization. tags: - Notifications parameters: - name: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 50 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: 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: 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: number 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: 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: 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: notificationId in: path required: true schema: format: uuid type: string - name: eventSubscriptionChannelId 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: userId 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: 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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: 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: 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: number 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/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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: 0 properties: next: example: 2 type: - number - "null" previous: example: 0 type: - number - "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: number 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/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: 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 description: Registers MQTT topics 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: command_name: example: restart type: string entity_id: example: b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f format: uuid type: string request_mqtt_topic: example: HS1040/task/request/aws/restart type: string response_mqtt_topic: example: HS1040/task/response/aws/restart type: string required: - entity_id - command_name - request_mqtt_topic - response_mqtt_topic type: object responses: "201": description: Resource created successfully content: application/json: schema: properties: command_name: example: restart 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: HS1040/task/request/aws/restart type: string response_mqtt_topic: example: HS1040/task/response/aws/restart 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 "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: type: string requestBody: required: true content: application/json: schema: properties: command_name: example: reboot type: string request_mqtt_topic: example: HS1040/task/request/aws/reboot type: string response_mqtt_topic: example: HS1040/task/response/aws/reboot 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 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: HS1040/task/request/aws/restart type: string response_mqtt_topic: example: HS1040/task/response/aws/restart 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: type: string responses: "200": description: Successful response content: application/json: schema: properties: command_name: example: restart 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: HS1040/task/request/aws/restart type: string response_mqtt_topic: example: HS1040/task/response/aws/restart 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/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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "null" required: - next - previous type: object results: items: properties: command_name: example: restart 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: HS1040/task/request/aws/restart type: string response_mqtt_topic: example: HS1040/task/response/aws/restart 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: number 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 requestBody: required: true content: application/json: schema: example: metadata: capabilities: - video - thermal manufacturer: DJI model: Mavic 3 name: Drone-1 organization_id: 550e8400-e29b-41d4-a716-446655440000 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 organization_id: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid 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: - organization_id - name - type - status type: object example: metadata: capabilities: - video - thermal manufacturer: DJI model: Mavic 3 name: Drone-1 organization_id: 550e8400-e29b-41d4-a716-446655440000 parent_id: a1b2c3d4-e5f6-7890-1234-567890abcdef status: active type: UAV 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 created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - status - affiliation - parent_id - created_at - updated_at 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 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 created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - status - affiliation - parent_id - created_at - updated_at 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 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 created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - status - affiliation - parent_id - created_at - updated_at 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: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: "" properties: next: example: 2 type: - number - "null" previous: example: "" type: - number - "null" required: - next - previous type: object results: items: properties: created_at: example: "2024-01-15T11:00:00Z" 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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: null type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number maxItems: 3 minItems: 3 type: array type: example: Point pattern: ^Point$ type: string required: - type - coordinates type: object recorded_at: example: "2024-01-15T11:00:00Z" type: string source: type: string required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: number 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 bulk locations description: Create or update multiple locations 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: locations: example: - Position: null RecordedAt: null Source: KALMAN_FILTER items: properties: 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 maxItems: 3 minItems: 3 type: array type: example: Point pattern: ^Point$ type: string required: - type - coordinates type: object recorded_at: example: "2023-10-01T12:00:00Z" type: string source: example: Helios type: string required: - position - source - recorded_at type: object type: array required: - locations type: object responses: "201": description: Created content: application/json: schema: items: {} 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 /v3/tracks/{trackId}/locations/{trackLocationId}: get: summary: Get track location description: Get a specific location for a track tags: - Track Locations parameters: - name: trackLocationId in: path required: true schema: format: uuid type: string - name: trackId 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: 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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: null type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number maxItems: 3 minItems: 3 type: array type: example: Point pattern: ^Point$ type: string required: - type - coordinates type: object recorded_at: example: "2024-01-15T11:00:00Z" type: string source: type: string 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 locations with complex filtering and pagination tags: - Track Locations parameters: - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number requestBody: required: true content: application/json: schema: example: filters: entity_ids: - c3d4e5f6-a1b2-7890-1234-567890abcdef recorded_after: null recorded_before: null future_only: "true" min_confidence: 0.8 sort: - {} properties: future_only: example: "true" type: boolean hydrate_entities: example: "true" type: boolean latest_only: example: "false" type: boolean min_confidence: example: 0.8 maximum: 1 minimum: 0 type: number sort: items: type: string type: array type: object example: filters: entity_ids: - c3d4e5f6-a1b2-7890-1234-567890abcdef recorded_after: null recorded_before: null future_only: "true" min_confidence: 0.8 sort: - {} responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: "" properties: next: example: 2 type: - number - "null" previous: example: "" type: - number - "null" required: - next - previous type: object results: items: properties: created_at: example: "2024-01-15T11:00:00Z" 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 id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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: null type: Point properties: coordinates: example: - 4.51759087e+06 - 0 - 4.48734841e+06 items: type: number maxItems: 3 minItems: 3 type: array type: example: Point pattern: ^Point$ type: string required: - type - coordinates type: object recorded_at: example: "2024-01-15T11:00:00Z" type: string source: type: string required: - id - entity_id - position - source - created_at type: object type: array total_count: example: 15 type: number 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/search: post: summary: Search tracks description: Search tracks with complex filtering and pagination tags: - Tracks parameters: - name: limit in: query required: false schema: maximum: 1000 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number 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 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 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: 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: "" properties: next: example: 2 type: - number - "null" previous: example: "" type: - number - "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 created_at: example: "2024-01-15T11:00:00Z" type: string deleted_at: type: string id: example: c3d4e5f6-a1b2-7890-1234-567890abcdef format: uuid type: string 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 - status - affiliation - parent_id - created_at - updated_at type: object type: array total_count: example: 25 type: number 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: maximum: 50 minimum: 1 type: number - name: offset in: query required: false schema: minimum: 0 type: number responses: "200": description: Successful response content: application/json: schema: properties: paging: example: next: 2 previous: null properties: next: example: 2 type: - number - "null" previous: type: - number - "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: number 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_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_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_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: streamId in: path required: true schema: format: uuid type: string - name: entityId 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_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/search: post: summary: Search video streams description: Search for video streams within an organization using various filters tags: - Video Streams parameters: - name: offset in: query required: false schema: minimum: 0 type: number - name: limit in: query required: false schema: maximum: 100 minimum: 1 type: number 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: 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: - number - "null" previous: type: - number - "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_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: number 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