Endpoints by Category
2FA
GET
/api/v1/secure/auth/2fa/status
Get 2FA status
Returns enabled 2FA methods and backup code count
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"enabled_methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"enabled_at": {
"type": "string",
"format": "date-time"
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"delivery_target_masked": {
"type": "string",
"nullable": true
}
},
"required": [
"method"
]
}
},
"backup_codes_remaining": {
"type": "integer"
},
"requires_2fa": {
"type": "boolean",
"description": "Whether tenant requires 2FA"
}
},
"required": [
"enabled_methods",
"backup_codes_remaining",
"requires_2fa"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/enable/{method}
Enable 2FA method
Initiates 2FA setup for the specified method
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"delivery_target": {
"type": "string",
"description": "Phone number (SMS/WhatsApp) or email address (Email)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp"
]
},
"secret": {
"type": "string",
"description": "Base32 encoded secret (show to user once)"
},
"qr_code_uri": {
"type": "string",
"description": "otpauth:// URI for QR code generation"
},
"qr_code_data_url": {
"type": "string",
"description": "Data URL of QR code image"
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "One-time backup codes (10 codes)"
}
},
"required": [
"method",
"secret",
"qr_code_uri",
"backup_codes"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"sms",
"email",
"whatsapp"
]
},
"delivery_target": {
"type": "string",
"description": "Masked phone/email"
},
"verification_sent": {
"type": "boolean"
},
"expires_in_seconds": {
"type": "integer",
"description": "Code expiration time"
}
},
"required": [
"method",
"delivery_target",
"verification_sent"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/verify
Verify 2FA code
Verifies a 2FA code and enables the method if valid
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"code": {
"type": "string",
"minLength": 6,
"maxLength": 8,
"description": "6-8 digit verification code"
}
},
"required": [
"method",
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"verified": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"method",
"verified"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/auth/2fa/disable
Disable 2FA method
Disables a 2FA method (requires current code or backup code)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"code": {
"type": "string",
"minLength": 6,
"maxLength": 8,
"description": "Current 2FA code to confirm disable"
}
},
"required": [
"method",
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"disabled": {
"type": "boolean"
}
},
"required": [
"method",
"disabled"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/send-code
Send verification code
Sends a new verification code via the specified method
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"sms",
"email",
"whatsapp"
],
"description": "Delivery method for the code"
}
},
"required": [
"method"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"sent": {
"type": "boolean"
},
"expires_in_seconds": {
"type": "integer"
}
}
}
},
"required": [
"success",
"message",
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/backup-codes
Generate backup codes
Generates new backup codes (invalidates any existing codes)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "New backup codes (previous codes are invalidated)"
},
"count": {
"type": "integer"
}
},
"required": [
"backup_codes",
"count"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/use-backup
Use backup code
Uses a one-time backup code for 2FA verification
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 8,
"maxLength": 12,
"description": "One-time backup code"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"used": {
"type": "boolean"
},
"remaining": {
"type": "integer"
}
}
}
},
"required": [
"success",
"message",
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
AI Providers
POST
/api/v1/secure/ai/providers/
Create external API provider
Create a new external API provider connector
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"api_key": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"api_name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"api_base_url": {
"type": "string",
"minLength": 1
},
"config": {
"type": "object"
},
"auth_config": {
"type": "object"
},
"enabled": {
"type": "boolean"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"description": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"default": "app_service"
}
},
"required": [
"api_key",
"api_name",
"api_base_url"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/ai/providers/
List external API providers
List all external API provider connectors with optional filtering
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/ai/providers/dashboard
Get AI provider dashboard metrics
Get aggregated metrics and statistics for all AI providers
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_providers": {
"type": "number"
},
"active_providers": {
"type": "number"
},
"inactive_providers": {
"type": "number"
},
"error_providers": {
"type": "number"
},
"uptime_percentage": {
"type": "number"
},
"avg_latency_ms": {
"type": "number"
},
"cache_hit_rate": {
"type": "number"
},
"recent_activity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"provider_name": {
"type": "string"
},
"status": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"latency_ms": {
"type": "number"
}
}
}
},
"provider_stats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider_key": {
"type": "string"
},
"provider_name": {
"type": "string"
},
"status": {
"type": "string"
},
"success_rate": {
"type": "number"
},
"avg_latency_ms": {
"type": "number"
},
"last_success": {
"type": [
"null",
"string"
]
},
"last_error": {
"type": [
"null",
"string"
]
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/ai/providers/{id}
Get external API provider
Get external API provider by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/ai/providers/{id}
Update external API provider
Update external API provider configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"api_name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"api_base_url": {
"type": "string",
"minLength": 1
},
"config": {
"type": "object"
},
"auth_config": {
"type": "object"
},
"enabled": {
"type": "boolean"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"description": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/ai/providers/{id}
Delete external API provider
Delete external API provider connector
📤 RESPONSE 204
Provider deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/ai/providers/{id}/enable
Enable external API provider
Enable an external API provider connector
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/ai/providers/{id}/disable
Disable external API provider
Disable an external API provider connector
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique connector ID"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Tenant ID (NULL = system-level)"
},
"api_key": {
"type": "string",
"description": "Unique API identifier (e.g., openrouter, rest_countries)"
},
"api_name": {
"type": "string",
"description": "Human-readable API name"
},
"api_base_url": {
"type": "string",
"description": "Full base URL for API requests (including version if applicable)"
},
"config": {
"type": "object",
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"description": "Encrypted authentication credentials (JSONB)"
},
"enabled": {
"type": "boolean",
"description": "Whether connector is enabled"
},
"priority": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Priority for failover (1 = highest)"
},
"status": {
"type": "string",
"enum": [
"active",
"degraded",
"offline",
"error",
"unknown"
],
"description": "Health status"
},
"last_health_check": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_success": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_details": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"consecutive_failures": {
"type": "integer",
"minimum": 0
},
"auto_disable_threshold": {
"type": "integer",
"minimum": 1,
"default": 5
},
"auto_disabled": {
"type": "boolean",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"category": {
"type": "string",
"enum": [
"system_sync",
"app_service",
"integration",
"communication"
],
"description": "Connector category: system_sync=background ref data, app_service=tenant AI/content, integration=third-party lookups, communication=messaging"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"api_key",
"api_name",
"api_base_url",
"enabled",
"priority",
"status",
"category",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
AI Translation
POST
/api/v1/secure/ai/translate/text
Translate text
Translate text from one language to another with optional HTML preservation
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"text",
"source_language",
"target_language"
],
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"target_language": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"preserve_html": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"translated_text": {
"type": "string"
},
"source_language": {
"type": "string"
},
"target_language": {
"type": "string"
},
"provider_used": {
"type": "string"
},
"model_used": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cached": {
"type": "boolean"
},
"char_count": {
"type": "number"
},
"tokens_used": {
"anyOf": [
{
"type": "object",
"properties": {
"input": {
"type": "number"
},
"output": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"input",
"output",
"total"
]
},
{
"type": "null"
}
]
}
},
"required": [
"translated_text",
"source_language",
"target_language",
"provider_used",
"cached",
"char_count"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/ai/translate/i18n
Translate i18n JSON structure
Translate i18n JSON for entity translations (batch mode)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"i18n_data"
],
"properties": {
"i18n_data": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"target_languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"languages_translated": {
"type": "array",
"items": {
"type": "string"
}
},
"provider_used": {
"type": "string"
},
"cached": {
"type": "boolean"
}
},
"required": [
"translations_i18n",
"languages_translated",
"provider_used",
"cached"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/ai/translate/entity
Translate entity
Translate space, resource, tag, or category and update database
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tag",
"category"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"target_languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"languages_translated": {
"type": "array",
"items": {
"type": "string"
}
},
"provider_used": {
"type": "string"
}
},
"required": [
"entity_id",
"entity_type",
"name",
"translations_i18n",
"languages_translated",
"provider_used"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
API Keys
GET
/api/v1/secure/api-keys/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"mcp_write_enabled",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of API key objects"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/api-keys/
No summary
Create a new API key with permission configuration. Returns the full key (only shown once!)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Human-readable name for the API key (1-100 chars)"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Optional description of key purpose (max 500 chars)"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n- `MCP_DEVELOPER`: Full tenant-admin level access for MCP tool usage and app development\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n \"resources\": {\n \"read\": true,\n \"write\": true,\n \"delete\": false,\n \"properties\": [\"currentLocation\", \"status\"]\n },\n \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n```"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Enable MCP mutating operations for this key (default: false)"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\", \"10.0.0.1\"])"
},
"device_fingerprint": {
"type": "string",
"description": "Optional device fingerprint for mobile attestation"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"mcp_write_enabled",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"fullKey": {
"type": "string",
"description": "CRITICAL: Full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"
},
"message": {
"type": "string",
"description": "Warning message to save the key securely"
}
},
"required": [
"data",
"fullKey",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/api-keys/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"mcp_write_enabled",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/api-keys/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Update API key name (1-100 chars)"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Update description (max 500 chars)"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n- `MCP_DEVELOPER`: Full tenant-admin level access for MCP tool usage and app development\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n \"resources\": {\n \"read\": true,\n \"write\": true,\n \"delete\": false,\n \"properties\": [\"currentLocation\", \"status\"]\n },\n \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n``` (partial update supported)"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Enable or disable MCP mutating operations for this key"
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the API key (false immediately revokes access)"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Update expiration timestamp (ISO 8601) or null to remove"
},
"ip_whitelist": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Update IP whitelist or null to remove restrictions"
},
"device_fingerprint": {
"type": [
"string",
"null"
],
"description": "Update device fingerprint or null to remove"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"mcp_write_enabled",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/api-keys/{id}
No summary
📤 RESPONSE 204
API key deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/api-keys/{id}/rotate
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Whether this API key can execute mutating MCP tools (create/update/delete/revoke)"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"mcp_write_enabled",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"fullKey": {
"type": "string",
"description": "CRITICAL: New full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"
},
"message": {
"type": "string",
"description": "Warning message to save the new key securely"
}
},
"required": [
"data",
"fullKey",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Admin
GET
/api/v1/secure/admin/flow-tasks/
List flow tasks
Get all flow tasks configured for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/admin/flow-tasks/
Create flow task
Create a new flow task for the tenant
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"type",
"name",
"targetRoute"
],
"properties": {
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"targetRoute": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 0,
"default": 0
},
"isMandatory": {
"type": "boolean",
"default": false
},
"isActive": {
"type": "boolean",
"default": true
},
"version": {
"type": "string",
"maxLength": 50,
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/admin/flow-tasks/{id}
Update flow task
Update an existing flow task
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"targetRoute": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 0
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"maxLength": 50,
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/admin/flow-tasks/{id}
Delete flow task
Delete a flow task from the tenant
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/admin/flow-tasks/{id}/reset
Reset task for all users
Reset a task completion for all users (e.g., when AGB version changes)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"resetCount": {
"type": "integer"
}
},
"required": [
"success",
"resetCount"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/admin/flow-tasks/reorder
Reorder flow tasks
Reorder tasks by providing task IDs in the desired priority order
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"taskIds"
],
"properties": {
"taskIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"description": "Task IDs in the desired priority order (first = highest priority)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"required": [
"success"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Integration control-plane tenant overrides list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"operation_key",
"operation_name",
"enabled",
"preferred_provider_order",
"quota_ceiling",
"override_config",
"updated_at"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
PUT
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Upsert integration control-plane tenant override
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"tenant_id",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"enabled",
"customer_credentials",
"quota_ceiling",
"preferred_provider_order",
"override_config",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
DELETE
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides/{id}
Delete integration control-plane tenant override
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deleted": {
"type": "boolean"
}
},
"required": [
"id",
"deleted"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations
Integration control-plane operations list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"operation_domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"system_scoped": {
"type": "boolean"
},
"request_count_24h": {
"type": "number"
},
"failure_count_24h": {
"type": "number"
}
},
"required": [
"operation_key",
"operation_name",
"operation_domain",
"enabled",
"system_scoped",
"request_count_24h",
"failure_count_24h"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations/{operationKey}
Integration control-plane operation detail
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"operation": {
"type": "object",
"additionalProperties": true
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_logs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"operation",
"metrics",
"recent_logs"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/overview
Integration telemetry overview
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_requests_24h": {
"type": "number"
},
"success_requests_24h": {
"type": "number"
},
"failure_requests_24h": {
"type": "number"
},
"success_rate_24h": {
"type": "number"
},
"warning_state_events_24h": {
"type": "number"
},
"error_state_events_24h": {
"type": "number"
},
"health_status": {
"type": "object",
"properties": {
"active": {
"type": "number"
},
"degraded": {
"type": "number"
},
"offline": {
"type": "number"
},
"error": {
"type": "number"
},
"unknown": {
"type": "number"
}
},
"required": [
"active",
"degraded",
"offline",
"error",
"unknown"
]
}
},
"required": [
"total_requests_24h",
"success_requests_24h",
"failure_requests_24h",
"success_rate_24h",
"warning_state_events_24h",
"error_state_events_24h",
"health_status"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/metrics
Integration hourly metrics
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/state
Integration state events
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"recent_failures": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_state_alerts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"latest_health_checks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"recent_failures",
"recent_state_alerts",
"latest_health_checks"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/system/security/config
Get global security configuration
Returns platform-wide security settings (DOS, rate limiting, cache, circuit breaker). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/config
Update global security configuration
Update platform-wide security settings. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"dos_time_window_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"dos_block_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 86400
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number",
"minimum": 100,
"maximum": 50000
},
"queue_timeout_ms": {
"type": "number",
"minimum": 1000,
"maximum": 120000
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number",
"minimum": 3,
"maximum": 100
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number",
"minimum": 300,
"maximum": 604800
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number",
"minimum": 50,
"maximum": 99
},
"circuit_breaker_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"circuit_breaker_check_interval_seconds": {
"type": "number",
"minimum": 5,
"maximum": 60
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"cache_default_ttl_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist
List IP blacklist entries
Returns all blocked IP addresses. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/security/ip-blacklist
Block an IP address
Add an IP address to the blacklist. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ip_address"
],
"properties": {
"ip_address": {
"type": "string",
"description": "IPv4 or IPv6 address"
},
"reason": {
"type": "string",
"maxLength": 255,
"description": "Reason for blocking"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Expiration time (null = permanent)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist/{id}
Get IP blacklist entry
Get details of a specific blocked IP. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/ip-blacklist/{id}
Update IP blacklist entry
Update reason or expiration of a blocked IP. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 255
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/security/ip-blacklist/{id}
Unblock an IP address
Remove an IP address from the blacklist. System admin only.
📤 RESPONSE 204
No content
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/events
List security events
Returns security audit log entries. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"ip_address": {
"type": "string",
"nullable": true
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/metrics
Get security metrics
Returns aggregated security metrics (blocked IPs, events, etc.). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_blocked_ips": {
"type": "number"
},
"active_blocked_ips": {
"type": "number"
},
"permanent_blocks": {
"type": "number"
},
"temporary_blocks": {
"type": "number"
},
"auto_blocked_count": {
"type": "number"
},
"events_last_24h": {
"type": "number"
},
"events_by_type": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"events_by_severity": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/
Query historical logs
System admin only. Query and filter application logs with pagination.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"level": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
},
"message": {
"type": "string"
},
"service": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"userId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"requestId": {
"type": "string",
"nullable": true
},
"context": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"timestamp",
"level",
"message"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/analytics
Get log analytics
System admin only. Get error rates, charts, and performance metrics.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"errorRate": {
"type": "number"
},
"errorCount": {
"type": "number"
},
"totalRequests": {
"type": "number"
},
"responseTime": {
"type": "object",
"properties": {
"p50": {
"type": "number"
},
"p95": {
"type": "number"
},
"p99": {
"type": "number"
}
},
"additionalProperties": false
},
"topErrors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"count": {
"type": "number"
},
"lastOccurrence": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"tenantActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"requestCount": {
"type": "number"
},
"errorCount": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/security-audit
Get security audit log
System admin only. Get security-related events (failed logins, permission denials, etc.).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"eventType": {
"type": "string",
"enum": [
"login_failed",
"permission_denied",
"api_key_used",
"admin_action"
]
},
"userId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/config
Get log configuration
System admin only. Get current log level configuration, formatting, and cleanup settings.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"description": "Per-service log levels",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"console": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"colorize": {
"type": "boolean"
},
"timestamp": {
"type": "boolean"
}
},
"additionalProperties": false
},
"database": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"table": {
"type": "string"
},
"batchSize": {
"type": "number"
},
"flushInterval": {
"type": "number"
}
},
"additionalProperties": false
},
"formatting": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"includeTimestamp": {
"type": "boolean"
},
"includeService": {
"type": "boolean"
},
"includeContext": {
"type": "boolean"
},
"redactSensitive": {
"type": "boolean"
}
},
"additionalProperties": false
},
"cleanup": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
},
"archiveEnabled": {
"type": "boolean"
},
"archiveLocation": {
"type": "string"
},
"cleanupSchedule": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/logs/config
Update log configuration
System admin only. Update log levels, formatting, and cleanup settings. Changes apply without restart.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"console": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"colorize": {
"type": "boolean"
},
"timestamp": {
"type": "boolean"
},
"levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
}
}
},
"database": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"table": {
"type": "string"
},
"batchSize": {
"type": "number",
"minimum": 1,
"maximum": 1000
},
"flushInterval": {
"type": "number",
"minimum": 1000,
"maximum": 60000
},
"levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
}
}
},
"formatting": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"includeTimestamp": {
"type": "boolean"
},
"includeService": {
"type": "boolean"
},
"includeContext": {
"type": "boolean"
},
"redactSensitive": {
"type": "boolean"
}
}
},
"cleanup": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
},
"archiveEnabled": {
"type": "boolean"
},
"archiveLocation": {
"type": "string"
},
"cleanupSchedule": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"applied": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/config/{section}
Get section configuration
System admin only. Get configuration for a specific section.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/logs/config/{section}
Update section configuration
System admin only. Update configuration for a specific section. Changes apply without restart.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"additionalProperties": true
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"applied": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/validate
Validate log configuration
System admin only. Validate configuration before saving. Returns errors and warnings.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"section": {
"type": "string",
"enum": [
"console",
"database",
"formatting",
"cleanup",
"log-levels"
]
},
"config": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"config"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/preview
Preview configuration changes
System admin only. Preview affected services and impact of configuration changes (AC15 requirement).
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"cleanup": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"affectedServices": {
"type": "array",
"items": {
"type": "string"
}
},
"estimatedLogVolume": {
"type": "number"
},
"storageImpact": {
"type": "object",
"properties": {
"current": {
"type": "number"
},
"projected": {
"type": "number"
},
"change": {
"type": "number"
}
},
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/export
Export logs to storage
System admin only. Export logs to pve-system storage bucket for archiving or analysis.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"level": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
},
"format": {
"type": "string",
"enum": [
"json",
"csv"
],
"default": "json"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"path": {
"type": "string"
},
"recordCount": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"required": [
"message",
"path",
"recordCount",
"sizeBytes"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/exports
List log exports
System admin only. List available log export files in storage.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"size": {
"type": "number"
},
"createdAt": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/logs/exports/{filename}
Delete log export
System admin only. Delete a log export file from storage.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"deleted": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/reset
Reset log configuration to defaults
System admin only. Reset all log settings to default values.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"reset": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/system/stats
No summary
Get system-wide storage statistics (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_tenants": {
"type": "number"
},
"enabled_tenants": {
"type": "number"
},
"total_quota_bytes": {
"type": "number"
},
"total_usage_bytes": {
"type": "number"
},
"average_usage_percent": {
"type": "number"
}
},
"required": [
"total_tenants",
"enabled_tenants",
"total_quota_bytes",
"total_usage_bytes",
"average_usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Application Accounts
GET
/api/v1/secure/app-accounts/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/
No summary
Create a new app account with optional permission configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"email",
"password"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"maxLength": 500
},
"password": {
"type": "string",
"minLength": 12,
"description": "Minimum 12 characters"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Optional permission configuration for this app account"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/app-accounts/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/app-accounts/{id}
No summary
Update app account details including permissions
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/app-accounts/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/{id}/regenerate-password
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/{id}/set-password
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
},
"message": {
"type": "string"
}
},
"required": [
"data"
],
"additionalProperties": true
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/app-accounts/{id}/usage-stats
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
],
"additionalProperties": true
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Approval
GET
/api/v1/secure/tenant/approval-settings
Get approval settings
Get approval settings for all entity types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"requires_approval": {
"type": "boolean"
},
"config": {
"type": "object",
"properties": {
"auto_approve_roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Roles that can auto-approve entities (default: owner, admin)",
"default": [
"owner",
"admin"
]
},
"max_pending_days": {
"type": "number",
"description": "Maximum days an approval can be pending before expiring",
"default": 30,
"minimum": 1,
"maximum": 365
},
"notify_admins": {
"type": "boolean",
"description": "Whether to notify admins when a new approval request is created",
"default": true
},
"notify_creator_on_decision": {
"type": "boolean",
"description": "Whether to notify the creator when the request is approved/rejected",
"default": true
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/tenant/approval-settings/{entityType}
Update approval settings
Update approval settings for an entity type (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"requires_approval": {
"type": "boolean"
},
"config": {
"type": "object",
"properties": {
"auto_approve_roles": {
"type": "array",
"items": {
"type": "string"
}
},
"max_pending_days": {
"type": "number",
"minimum": 1,
"maximum": 365
},
"notify_admins": {
"type": "boolean"
},
"notify_creator_on_decision": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"requires_approval": {
"type": "boolean"
},
"config": {
"type": "object",
"properties": {
"auto_approve_roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Roles that can auto-approve entities (default: owner, admin)",
"default": [
"owner",
"admin"
]
},
"max_pending_days": {
"type": "number",
"description": "Maximum days an approval can be pending before expiring",
"default": 30,
"minimum": 1,
"maximum": 365
},
"notify_admins": {
"type": "boolean",
"description": "Whether to notify admins when a new approval request is created",
"default": true
},
"notify_creator_on_decision": {
"type": "boolean",
"description": "Whether to notify the creator when the request is approved/rejected",
"default": true
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/approvals
List approval requests
List approval requests
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data",
"total",
"limit",
"offset"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string"
}
}
},
"decider": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string"
}
}
}
}
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/approvals/{id}
Get approval request
Get an approval request by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string"
}
}
},
"decider": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/approvals/{id}
Cancel request
Cancel a pending approval request (creator or admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data",
"message"
],
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/approvals/{id}/approve
Approve request
Approve a pending approval request (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"comment": {
"type": "string",
"maxLength": 500
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data",
"message"
],
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/approvals/{id}/reject
Reject request
Reject a pending approval request (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"rejection_reason"
],
"properties": {
"rejection_reason": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data",
"message"
],
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/me/approvals
Get my approval requests
Get current user's approval requests
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data",
"total"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"calendar_entry"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
"reason": {
"type": "string"
},
"decision_at": {
"type": "string",
"format": "date-time"
},
"decision_by": {
"type": "string",
"format": "uuid"
},
"rejection_reason": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"total": {
"type": "number"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Audit Logs
GET
/api/v1/secure/audit-logs/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"action": {
"type": "string"
},
"resource_type": {
"type": "string"
},
"resource_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"details": {
"type": "object",
"additionalProperties": true,
"nullable": true
},
"ip_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user_agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"action",
"resource_type",
"created_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Auth
POST
/api/v1/public/auth/login
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"rememberMe": {
"type": "boolean"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Optional tenant ID for multi-tenant login. If not provided and user has multiple tenants, returns tenant list."
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"groupDetails": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"permissions"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"permissions": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"isSystemAdmin": {
"type": "boolean"
},
"isTenantAdmin": {
"type": "boolean"
}
},
"required": [
"id",
"email",
"tenantId",
"groups",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"expiresIn": {
"type": "number"
}
},
"required": [
"user",
"accessToken",
"refreshToken",
"expiresIn"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/register
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password",
"tenantName",
"tenantDomain"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"tenantName": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"tenantDomain": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 63
},
"displayName": {
"type": "string",
"maxLength": 255
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"tenantId": {
"type": "string"
}
}
},
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"domain": {
"type": "string"
}
}
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/refresh
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"refreshToken": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"expiresIn": {
"type": "number"
}
},
"required": [
"accessToken",
"refreshToken",
"expiresIn"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/logout
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/auth/providers
Get enabled OAuth providers
Returns a list of OAuth providers that are enabled for authentication, along with tenant-specific settings
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"description": "Provider identifier"
},
"name": {
"type": "string",
"description": "Display name for the provider"
},
"enabled": {
"type": "boolean",
"description": "Whether this provider is enabled"
},
"icon": {
"type": "string",
"description": "Icon name or URL for the provider"
}
},
"required": [
"id",
"name",
"enabled"
],
"additionalProperties": false
},
"description": "List of available OAuth providers"
},
"emailEnabled": {
"type": "boolean",
"description": "Whether email/password login is enabled"
},
"tenantConfig": {
"type": "object",
"properties": {
"requireInvitation": {
"type": "boolean",
"description": "Whether users must have an invitation to register"
},
"allowSelfRegistration": {
"type": "boolean",
"description": "Whether users can self-register without invitation"
},
"passwordAuthEnabled": {
"type": "boolean",
"description": "Whether email/password authentication is enabled"
},
"mfaRequired": {
"type": "boolean",
"description": "Whether MFA is required for all users"
}
},
"required": [
"requireInvitation",
"allowSelfRegistration",
"passwordAuthEnabled",
"mfaRequired"
],
"additionalProperties": false,
"description": "Tenant-specific authentication configuration"
}
},
"required": [
"data",
"emailEnabled"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/oauth/init
Initiate OAuth flow
Starts OAuth authentication with the specified provider
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"description": "OAuth provider to authenticate with"
},
"redirectUrl": {
"type": "string",
"format": "uri",
"description": "URL to redirect to after authentication"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Optional tenant ID for multi-tenant login"
}
},
"required": [
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "OAuth provider authorization URL"
},
"provider": {
"type": "string",
"description": "The provider being used"
}
},
"required": [
"url",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/oauth/register
Complete OAuth registration
Creates a platform account for an OAuth-authenticated user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"displayName": {
"type": "string"
},
"registrationMode": {
"type": "string",
"enum": [
"create_tenant",
"join_tenant",
"system_tenant"
]
},
"tenantName": {
"type": "string"
},
"tenantDomain": {
"type": "string"
},
"inviteCode": {
"type": "string"
},
"locale": {
"type": "string"
}
},
"required": [
"accessToken",
"refreshToken",
"registrationMode"
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"tenantName": {
"type": "string"
}
}
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"requiresPostAuthFlow": {
"type": "boolean"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/register-user
Register new user
Self-service user registration with email verification
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"displayName": {
"type": "string",
"maxLength": 255
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"userId": {
"type": "string",
"format": "uuid"
},
"requiresVerification": {
"type": "boolean"
}
},
"required": [
"message",
"userId",
"requiresVerification"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/resend-verification
Resend verification email
Resend email verification to a registered but unverified user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/forgot-password
Request password reset
Send password reset email to user. Always returns success for security.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/auth/validate-reset-token
Validate reset token
Check if a password reset token is valid and not expired
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"email": {
"type": "string",
"format": "email"
}
},
"required": [
"valid"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/reset-password
Reset password
Set new password using a valid reset token. Token is single-use.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"token",
"password"
],
"properties": {
"token": {
"type": "string",
"minLength": 1
},
"password": {
"type": "string",
"minLength": 8
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/auth/user-tenants
Get user tenants by email
Returns list of tenants the user has access to. For security, always returns an empty list for non-existent users.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tenants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug"
]
}
},
"hasMultipleTenants": {
"type": "boolean"
}
},
"required": [
"tenants",
"hasMultipleTenants"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/auth/me
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"displayName": {
"type": "string"
},
"locale": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenantId"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/auth/identities
List linked identities
Returns all OAuth providers linked to the current user account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"email": {
"type": "string",
"format": "email",
"nullable": true
},
"display_name": {
"type": "string",
"nullable": true
},
"avatar_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"linked_at": {
"type": "string",
"format": "date-time"
},
"last_login_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"is_primary": {
"type": "boolean",
"description": "Whether this is the primary login method"
}
},
"required": [
"id",
"provider",
"linked_at"
],
"additionalProperties": false
}
},
"email_auth_enabled": {
"type": "boolean",
"description": "Whether email/password authentication is enabled for this user"
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"email_auth_enabled",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/link/{provider}
Link OAuth provider
Initiates OAuth flow to link a new provider to the current account
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"redirectUrl": {
"type": "string",
"format": "uri",
"description": "URL to redirect to after OAuth linking completes"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "OAuth authorization URL for linking"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
}
},
"required": [
"url",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/auth/unlink/{provider}
Unlink OAuth provider
Removes a linked OAuth provider from the current account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
}
},
"required": [
"success",
"message",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/auth/primary/{provider}
Set primary provider
Sets the primary login method for the account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"primary_provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github",
"email"
]
}
},
"required": [
"success",
"message",
"primary_provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/oauth-history
Get OAuth login history
Returns recent OAuth login attempts for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string"
},
"success": {
"type": "boolean"
},
"attempted_at": {
"type": "string",
"format": "date-time"
},
"ip_address": {
"type": "string",
"nullable": true
}
}
}
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"total"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/2fa/status
Get 2FA status
Returns enabled 2FA methods and backup code count
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"enabled_methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"enabled_at": {
"type": "string",
"format": "date-time"
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"delivery_target_masked": {
"type": "string",
"nullable": true
}
},
"required": [
"method"
]
}
},
"backup_codes_remaining": {
"type": "integer"
},
"requires_2fa": {
"type": "boolean",
"description": "Whether tenant requires 2FA"
}
},
"required": [
"enabled_methods",
"backup_codes_remaining",
"requires_2fa"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/enable/{method}
Enable 2FA method
Initiates 2FA setup for the specified method
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"delivery_target": {
"type": "string",
"description": "Phone number (SMS/WhatsApp) or email address (Email)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"oneOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp"
]
},
"secret": {
"type": "string",
"description": "Base32 encoded secret (show to user once)"
},
"qr_code_uri": {
"type": "string",
"description": "otpauth:// URI for QR code generation"
},
"qr_code_data_url": {
"type": "string",
"description": "Data URL of QR code image"
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "One-time backup codes (10 codes)"
}
},
"required": [
"method",
"secret",
"qr_code_uri",
"backup_codes"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"sms",
"email",
"whatsapp"
]
},
"delivery_target": {
"type": "string",
"description": "Masked phone/email"
},
"verification_sent": {
"type": "boolean"
},
"expires_in_seconds": {
"type": "integer",
"description": "Code expiration time"
}
},
"required": [
"method",
"delivery_target",
"verification_sent"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/verify
Verify 2FA code
Verifies a 2FA code and enables the method if valid
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"code": {
"type": "string",
"minLength": 6,
"maxLength": 8,
"description": "6-8 digit verification code"
}
},
"required": [
"method",
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"verified": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
}
},
"required": [
"method",
"verified"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/auth/2fa/disable
Disable 2FA method
Disables a 2FA method (requires current code or backup code)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"code": {
"type": "string",
"minLength": 6,
"maxLength": 8,
"description": "Current 2FA code to confirm disable"
}
},
"required": [
"method",
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"totp",
"sms",
"email",
"whatsapp"
]
},
"disabled": {
"type": "boolean"
}
},
"required": [
"method",
"disabled"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/send-code
Send verification code
Sends a new verification code via the specified method
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"sms",
"email",
"whatsapp"
],
"description": "Delivery method for the code"
}
},
"required": [
"method"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"sent": {
"type": "boolean"
},
"expires_in_seconds": {
"type": "integer"
}
}
}
},
"required": [
"success",
"message",
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/backup-codes
Generate backup codes
Generates new backup codes (invalidates any existing codes)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "New backup codes (previous codes are invalidated)"
},
"count": {
"type": "integer"
}
},
"required": [
"backup_codes",
"count"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/2fa/use-backup
Use backup code
Uses a one-time backup code for 2FA verification
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 8,
"maxLength": 12,
"description": "One-time backup code"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"used": {
"type": "boolean"
},
"remaining": {
"type": "integer"
}
}
}
},
"required": [
"success",
"message",
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/me
Get current user
Get the current authenticated user profile, tenant context, groups, and permissions
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"groupDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"permissions"
],
"additionalProperties": false
}
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"isSystemAdmin": {
"type": "boolean"
},
"isTenantAdmin": {
"type": "boolean"
}
},
"required": [
"id",
"email",
"displayName",
"tenantId",
"tenantName",
"groups",
"groupDetails",
"permissions",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
}
},
"required": [
"user"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/tenants
Get user tenants
Returns list of tenants the current user has access to
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"pending",
"invited"
]
},
"is_default": {
"type": "boolean"
},
"joined_at": {
"type": "string",
"format": "date-time"
},
"tenant_name": {
"type": "string"
},
"tenant_slug": {
"type": "string"
}
},
"required": [
"user_id",
"tenant_id",
"role",
"tenant_name",
"tenant_slug"
],
"additionalProperties": false
}
},
"active_tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"default_tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/switch-tenant
Switch tenant
Switch the active tenant for the current session
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Target tenant ID to switch to"
}
},
"required": [
"tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"tenant_slug": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"success",
"tenant_id",
"tenant_name",
"tenant_slug",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/auth/default-tenant
Set default tenant
Set the default tenant that will be used on login
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant ID to set as default"
}
},
"required": [
"tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"default_tenant_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"success",
"default_tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/leave-tenant/{tenantId}
Leave tenant
Remove yourself from a tenant membership
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/tenant-role
Get tenant role
Get the current user's role in the active tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"tenant_id",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/resolve-flow
Resolve auth flow
Evaluate user state and return the next step after authentication
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"context"
],
"properties": {
"context": {
"type": "string",
"enum": [
"login",
"registration",
"verification",
"invitation"
],
"description": "The authentication context that triggered this resolve"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"REDIRECT",
"PROCEED"
]
},
"target": {
"type": "string",
"description": "Route to redirect to, or dashboard if PROCEED"
},
"taskId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"pendingTasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"isMandatory": {
"type": "boolean"
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"isMandatory"
]
}
}
},
"required": [
"action",
"target",
"pendingTasks"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/tasks/status
Get tasks status
Get all tasks with completion status for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isCompleted": {
"type": "boolean"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completedVersion": {
"type": "string",
"nullable": true
},
"currentVersion": {
"type": "string",
"nullable": true
},
"requiresUpdate": {
"type": "boolean",
"description": "True if AGB version changed"
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isCompleted"
]
}
},
"mandatoryCompleted": {
"type": "integer"
},
"mandatoryTotal": {
"type": "integer"
},
"optionalCompleted": {
"type": "integer"
},
"optionalTotal": {
"type": "integer"
}
},
"required": [
"tasks",
"mandatoryCompleted",
"mandatoryTotal",
"optionalCompleted",
"optionalTotal"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/tasks/{taskId}/complete
Complete task
Mark a task as completed for the current user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Optional metadata for the task completion (e.g., AGB acceptance data)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"taskId": {
"type": "string",
"format": "uuid"
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"nextAction": {
"type": "string",
"enum": [
"REDIRECT",
"PROCEED"
]
},
"nextTarget": {
"type": "string"
},
"nextTaskId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"success",
"taskId",
"completedAt",
"nextAction",
"nextTarget"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
AuthHelper
POST
/api/v1/secure/auth/resolve-flow
Resolve auth flow
Evaluate user state and return the next step after authentication
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"context"
],
"properties": {
"context": {
"type": "string",
"enum": [
"login",
"registration",
"verification",
"invitation"
],
"description": "The authentication context that triggered this resolve"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"REDIRECT",
"PROCEED"
]
},
"target": {
"type": "string",
"description": "Route to redirect to, or dashboard if PROCEED"
},
"taskId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"pendingTasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"isMandatory": {
"type": "boolean"
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"isMandatory"
]
}
}
},
"required": [
"action",
"target",
"pendingTasks"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/tasks/status
Get tasks status
Get all tasks with completion status for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isCompleted": {
"type": "boolean"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completedVersion": {
"type": "string",
"nullable": true
},
"currentVersion": {
"type": "string",
"nullable": true
},
"requiresUpdate": {
"type": "boolean",
"description": "True if AGB version changed"
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isCompleted"
]
}
},
"mandatoryCompleted": {
"type": "integer"
},
"mandatoryTotal": {
"type": "integer"
},
"optionalCompleted": {
"type": "integer"
},
"optionalTotal": {
"type": "integer"
}
},
"required": [
"tasks",
"mandatoryCompleted",
"mandatoryTotal",
"optionalCompleted",
"optionalTotal"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/tasks/{taskId}/complete
Complete task
Mark a task as completed for the current user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Optional metadata for the task completion (e.g., AGB acceptance data)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"taskId": {
"type": "string",
"format": "uuid"
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"nextAction": {
"type": "string",
"enum": [
"REDIRECT",
"PROCEED"
]
},
"nextTarget": {
"type": "string"
},
"nextTaskId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"success",
"taskId",
"completedAt",
"nextAction",
"nextTarget"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/admin/flow-tasks/
List flow tasks
Get all flow tasks configured for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/admin/flow-tasks/
Create flow task
Create a new flow task for the tenant
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"type",
"name",
"targetRoute"
],
"properties": {
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"targetRoute": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 0,
"default": 0
},
"isMandatory": {
"type": "boolean",
"default": false
},
"isActive": {
"type": "boolean",
"default": true
},
"version": {
"type": "string",
"maxLength": 50,
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/admin/flow-tasks/{id}
Update flow task
Update an existing flow task
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"targetRoute": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"priority": {
"type": "integer",
"minimum": 0
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"maxLength": 50,
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"agb",
"profile",
"kyc",
"avatar",
"phone_verification",
"email_verification",
"custom"
]
},
"name": {
"type": "string"
},
"targetRoute": {
"type": "string"
},
"priority": {
"type": "integer"
},
"isMandatory": {
"type": "boolean"
},
"isActive": {
"type": "boolean"
},
"version": {
"type": "string",
"nullable": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"buttonText": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"type",
"name",
"targetRoute",
"priority",
"isMandatory",
"isActive"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/admin/flow-tasks/{id}
Delete flow task
Delete a flow task from the tenant
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/admin/flow-tasks/{id}/reset
Reset task for all users
Reset a task completion for all users (e.g., when AGB version changes)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"resetCount": {
"type": "integer"
}
},
"required": [
"success",
"resetCount"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/admin/flow-tasks/reorder
Reorder flow tasks
Reorder tasks by providing task IDs in the desired priority order
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"taskIds"
],
"properties": {
"taskIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"description": "Task IDs in the desired priority order (first = highest priority)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"required": [
"success"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Avatar
GET
/api/v1/secure/profile/avatar/sources
Get available avatar sources
Returns all available avatar sources including generated, uploaded, and OAuth provider avatars
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"currentSource": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Currently selected avatar source"
},
"currentIdentityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID if current source is remote"
},
"currentAvatarUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Current resolved avatar URL"
},
"availableSources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source type"
},
"previewUrl": {
"type": "string",
"format": "uri",
"description": "Preview URL for this avatar source"
},
"thumbnailUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Thumbnail URL (for uploaded avatars)"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID (for remote avatars)"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"nullable": true,
"description": "OAuth provider (for remote avatars)"
},
"providerName": {
"type": "string",
"nullable": true,
"description": "Display name of the OAuth provider"
}
},
"required": [
"type",
"previewUrl"
],
"additionalProperties": false
},
"description": "All available avatar sources for this user"
}
},
"required": [
"currentSource",
"availableSources"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/profile/avatar/
Set avatar source
Sets the avatar source for the current user profile
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source to set"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID (required when source is \"remote\")"
}
},
"required": [
"source"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"source"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/profile/avatar/
Reset avatar
Resets the avatar to generated mode (initials-based)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"description": "Generated avatar URL"
}
},
"required": [
"source",
"avatarUrl"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/profile/avatar/
Get current avatar
Returns the current avatar source and URL for the user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"source"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Calendar
GET
/api/v1/secure/calendar/
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Categories
GET
/api/v1/secure/taxonomy/categories/
No summary
List categories with optional filters (flat listing)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/
No summary
Create category (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"key",
"name"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 1,
"maxLength": 100
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Base language name"
},
"language": {
"type": "string",
"minLength": 2,
"maxLength": 5,
"description": "Base language ISO 639-1 code; defaults to tenant default_language"
},
"description": {
"type": [
"string",
"null"
],
"description": "Base language description"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"filter_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100
},
"translations_i18n": {
"type": "object",
"description": "Additional language translations ONLY — must NOT include the base language",
"additionalProperties": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/tree
No summary
Get category tree (hierarchical listing)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"children": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Recursive category structure"
},
"description": "Child categories (hierarchical)"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/{id}
No summary
Get category by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/categories/{id}
No summary
Update category (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 1,
"maxLength": 100
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Base language name"
},
"language": {
"type": "string",
"minLength": 2,
"maxLength": 5,
"description": "Base language ISO 639-1 code"
},
"description": {
"type": [
"string",
"null"
],
"description": "Base language description"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"filter_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100
},
"translations_i18n": {
"type": "object",
"description": "Additional language translations ONLY — must NOT include the base language",
"additionalProperties": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}
No summary
Delete category (admin only, requires replacement if links exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"replacement_category_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Category deleted successfully
Schema: Category deleted successfully
{
"description": "Category deleted successfully",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
},
"relinked_count": {
"type": "number"
},
"replacement_category_id": {
"type": [
"null",
"string"
]
}
}
}
}
}
PATCH
/api/v1/secure/taxonomy/categories/{id}/i18n
No summary
Upsert category translation (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"locale",
"name"
],
"properties": {
"locale": {
"type": "string",
"enum": [
"de",
"en",
"fr",
"it"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"locale": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"locale",
"name",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/{id}/link
No summary
Link category to entity
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}/unlink
No summary
Unlink category from entity
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Category unlinked successfully
GET
/api/v1/secure/taxonomy/categories/entity
No summary
Get all categories for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/{id}/entities
No summary
Get all entities with this category (reverse lookup filter)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/export
No summary
Export categories to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/taxonomy/categories/import
No summary
Import categories from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Chat
POST
/api/v1/secure/chat/conversations
Start or retrieve a peer conversation
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"participant_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the other user to chat with"
}
},
"required": [
"participant_id"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"participant_a": {
"type": "string",
"format": "uuid"
},
"participant_b": {
"type": "string",
"format": "uuid"
},
"last_message_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"last_message_preview": {
"type": [
"null",
"string"
]
},
"unread_count": {
"type": "number",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"participant_a",
"participant_b",
"unread_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"participant_a": {
"type": "string",
"format": "uuid"
},
"participant_b": {
"type": "string",
"format": "uuid"
},
"last_message_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"last_message_preview": {
"type": [
"null",
"string"
]
},
"unread_count": {
"type": "number",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"participant_a",
"participant_b",
"unread_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/chat/conversations
List conversations for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"participant_a": {
"type": "string",
"format": "uuid"
},
"participant_b": {
"type": "string",
"format": "uuid"
},
"last_message_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"last_message_preview": {
"type": [
"null",
"string"
]
},
"unread_count": {
"type": "number",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"participant_a",
"participant_b",
"unread_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data",
"pagination"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/chat/conversations/{id}
Get a single conversation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"participant_a": {
"type": "string",
"format": "uuid"
},
"participant_b": {
"type": "string",
"format": "uuid"
},
"last_message_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"last_message_preview": {
"type": [
"null",
"string"
]
},
"unread_count": {
"type": "number",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"participant_a",
"participant_b",
"unread_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/chat/conversations/{id}/channel
Get realtime channel name for a conversation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"channel_name": {
"type": "string",
"description": "Supabase Realtime channel name to subscribe to"
},
"conversation_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"channel_name",
"conversation_id"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/chat/conversations/{id}/messages
Send a message in a conversation
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "Message text (1–4000 chars)"
}
},
"required": [
"content"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"conversation_id": {
"type": "string",
"format": "uuid"
},
"sender_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"sent_at": {
"type": "string",
"format": "date-time"
},
"read_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"deleted_at": {
"type": [
"null",
"string"
],
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"conversation_id",
"sender_id",
"content",
"sent_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/chat/conversations/{id}/messages
List messages in a conversation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"conversation_id": {
"type": "string",
"format": "uuid"
},
"sender_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"sent_at": {
"type": "string",
"format": "date-time"
},
"read_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"deleted_at": {
"type": [
"null",
"string"
],
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"conversation_id",
"sender_id",
"content",
"sent_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"hasMore": {
"type": "boolean"
},
"nextCursor": {
"type": [
"null",
"string"
],
"description": "ISO timestamp cursor for next page"
}
},
"required": [
"hasMore",
"nextCursor"
]
}
},
"required": [
"data",
"pagination"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/chat/conversations/{id}/read
Mark all unread messages in a conversation as read
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"marked_count": {
"type": "number",
"description": "Number of messages marked as read"
}
},
"required": [
"marked_count"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/chat/conversations/{id}/messages/{msgId}
Soft-delete a message (own messages only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
}
},
"required": [
"deleted"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/chat/conversations/{id}/typing
Emit typing indicator for a conversation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"sent": {
"type": "boolean"
}
},
"required": [
"sent"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- Default Response
→ See StandardErrorResponse
Note: Contains additional properties: data
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/chat/unread-count
Get total unread message count for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_unread": {
"type": "number",
"minimum": 0
},
"conversations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"conversation_id": {
"type": "string",
"format": "uuid"
},
"unread_count": {
"type": "number",
"minimum": 0
}
},
"required": [
"conversation_id",
"unread_count"
]
}
}
},
"required": [
"total_unread",
"conversations"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Contacts
GET
/api/v1/secure/contacts/
No summary
List contacts with optional filters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/contacts/
No summary
Create a new contact
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"firstName": {
"type": "string",
"maxLength": 100,
"description": "Passport first name (romanized)"
},
"middleName": {
"type": "string",
"maxLength": 100,
"description": "Passport middle name (optional)"
},
"lastName": {
"type": "string",
"maxLength": 100,
"description": "Passport last name (romanized)"
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string",
"maxLength": 50
},
"url": {
"type": "string",
"format": "uri"
},
"address": {
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
"notes": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/contacts/{id}
No summary
Get a contact by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/contacts/{id}
No summary
Update a contact
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"firstName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport first name (romanized)"
},
"middleName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport middle name (optional)"
},
"lastName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport last name (romanized)"
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
]
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 50
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/contacts/{id}
No summary
Delete a contact
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/contacts/{id}/references
No summary
Get all entities (users, spaces, resources) linked to a contact
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"entity_description": {
"type": [
"null",
"string"
]
},
"entity_status": {
"type": [
"null",
"string"
]
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"entity_type",
"entity_id",
"entity_name",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/contacts
No summary
Get contacts linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/contacts
No summary
Link a contact to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/contacts/{contactId}
No summary
Unlink a contact from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/contacts
No summary
Get contacts linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/contacts
No summary
Link a contact to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/contacts/{contactId}
No summary
Unlink a contact from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/contacts
No summary
Get contacts linked to a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/{id}/contacts
No summary
Link a contact to a user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/users/{id}/contacts/{contactId}
No summary
Unlink a contact from a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/export
No summary
Export contacts to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/users/import
No summary
Import contacts from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Countries (Public)
GET
/api/v1/public/countries/
List all countries with optional filters and prioritization
Get all countries with optional search, region filter, localization, and prioritized sorting. Priority countries appear first, followed by alphabetically sorted remaining countries. No tenant isolation - same data for all tenants.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"cca3": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"description": "ISO 3166-1 alpha-3 country code (3 uppercase letters)",
"example": "CHE"
},
"name_ascii": {
"type": "string",
"description": "International country name in English (ASCII-safe)",
"example": "Switzerland"
},
"name_local": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Localized country names per language code",
"example": {
"de": "Schweiz",
"fr": "Suisse",
"it": "Svizzera",
"rm": "Svizra"
}
},
"flag_url": {
"type": "string",
"format": "uri",
"description": "Flag image URL from FlagsAPI.com",
"example": "https://flagsapi.com/CH/flat/64.png"
},
"currencies": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"nullable": true,
"description": "ISO 4217 currency codes used in this country",
"example": [
"CHF"
]
},
"phone_code": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"nullable": true,
"description": "International Direct Dialing code",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"region": {
"type": "string",
"example": "Europe"
},
"calling_code": {
"type": "string",
"example": "+41"
},
"currency_code": {
"type": "string",
"example": "CHF"
},
"capital": {
"type": "string",
"example": "Bern"
}
},
"additionalProperties": true,
"description": "Additional metadata (region, calling code, currency, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was last updated"
},
"name": {
"type": "string",
"description": "Localized name based on language query parameter (computed field)",
"example": "Schweiz"
}
},
"required": [
"iso_code",
"name_ascii",
"name_local",
"flag_url",
"metadata",
"created_at",
"updated_at",
"name"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of countries matching filters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"description": "Number of countries per page"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of countries skipped"
}
},
"required": [
"countries",
"total",
"limit",
"offset"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/countries/regions
Get unique regions list
Get list of unique regions from country metadata (e.g., Europe, Asia, Americas).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"regions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of unique regions from country metadata",
"example": [
"Africa",
"Americas",
"Asia",
"Europe",
"Oceania"
]
}
},
"required": [
"regions"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/countries/{isoCode}
Get country by ISO code
Get single country by ISO 3166-1 alpha-2 code (e.g., CH, DE, TH). Returns localized name based on language parameter or Accept-Language header.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"name_ascii": {
"type": "string",
"description": "International country name in English (ASCII-safe)",
"example": "Switzerland"
},
"name_local": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Localized country names per language code",
"example": {
"de": "Schweiz",
"fr": "Suisse",
"it": "Svizzera",
"rm": "Svizra"
}
},
"flag_url": {
"type": "string",
"format": "uri",
"description": "Flag image URL from FlagsAPI.com",
"example": "https://flagsapi.com/CH/flat/64.png"
},
"metadata": {
"type": "object",
"properties": {
"region": {
"type": "string",
"example": "Europe"
},
"calling_code": {
"type": "string",
"example": "+41"
},
"currency_code": {
"type": "string",
"example": "CHF"
},
"capital": {
"type": "string",
"example": "Bern"
},
"languages": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"de",
"fr",
"it",
"rm",
"en"
]
}
},
"additionalProperties": true,
"description": "Additional metadata (region, calling code, currency, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was last updated"
},
"name": {
"type": "string",
"description": "Localized name based on language query parameter (computed field)",
"example": "Schweiz"
}
},
"required": [
"iso_code",
"name_ascii",
"name_local",
"flag_url",
"metadata",
"created_at",
"updated_at",
"name"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Export/Import
GET
/api/v1/services/messaging/templates/{id}/export
No summary
Export a single message template as JSON
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"null",
"string"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string"
},
"version": {
"type": "number"
}
},
"required": [
"name",
"channel",
"content",
"variables",
"language",
"version"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/templates/export
No summary
Export all message templates for the tenant as JSON bundle
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Bundle version (e.g., \"1.0\")"
},
"exportedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"tenantId"
]
},
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"null",
"string"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string"
},
"version": {
"type": "number"
}
},
"required": [
"name",
"channel",
"content",
"variables",
"language",
"version"
]
}
}
},
"required": [
"version",
"exportedAt",
"source",
"templates"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/templates/import
No summary
Import message templates from JSON. Supports individual templates or bundle format.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
}
},
"required": [
"name",
"channel",
"content"
]
}
},
"options": {
"type": "object",
"properties": {
"mergeStrategy": {
"type": "string",
"enum": [
"skip",
"replace",
"merge"
],
"default": "skip",
"description": "How to handle existing templates: skip (keep existing), replace (overwrite), merge (update only empty fields)"
},
"dryRun": {
"type": "boolean",
"default": false,
"description": "If true, validate without saving"
}
}
}
},
"required": [
"templates"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Template index in input array"
},
"name": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/type-definitions/{id}/export
No summary
Export a single type definition as JSON
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description"
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
],
"description": "Entity type this definition applies to"
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName",
"isMandatory",
"displayOrder"
]
},
"description": "Property schemas for this type definition"
}
},
"required": [
"name",
"label",
"appliesTo",
"properties"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/type-definitions/export
No summary
Export all type definitions for the tenant as JSON bundle
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Bundle version (e.g., \"1.0\")"
},
"exportedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"tenantId"
]
},
"typeDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description"
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
],
"description": "Entity type this definition applies to"
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName",
"isMandatory",
"displayOrder"
]
},
"description": "Property schemas for this type definition"
}
},
"required": [
"name",
"label",
"appliesTo",
"properties"
]
}
}
},
"required": [
"version",
"exportedAt",
"source",
"typeDefinitions"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/type-definitions/import
No summary
Import type definitions from JSON. Supports individual type definitions or bundle format.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"typeDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case, validated in service)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"string",
"null"
]
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
]
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName"
]
}
}
},
"required": [
"name",
"label",
"appliesTo"
]
}
},
"options": {
"type": "object",
"properties": {
"mergeStrategy": {
"type": "string",
"enum": [
"skip",
"replace",
"merge"
],
"default": "skip",
"description": "How to handle existing type definitions: skip (keep existing), replace (overwrite), merge (update only empty fields)"
},
"dryRun": {
"type": "boolean",
"default": false,
"description": "If true, validate without saving"
}
}
}
},
"required": [
"typeDefinitions"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"duplicates": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Type definition index in input array"
},
"identifier": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/type-definitions/export/excel
No summary
Export type definitions to Excel/CSV/TSV format (shared system)
📤 RESPONSE 200
Inline Schema
Response: Binary file download (xlsx, csv, or tsv)
Schema: Binary file download (xlsx, csv, or tsv)
{
"description": "Binary file download (xlsx, csv, or tsv)",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/type-definitions/import/excel
No summary
Import type definitions from Excel/CSV/TSV file (shared system)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"duplicates": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Type definition index in input array"
},
"identifier": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/export/{entityType}
Export entities to Excel/CSV/TSV
Export entities of the specified type to Excel (xlsx), CSV, or TSV format.
**Supported Entity Types:**
- resources: Resources with categories, tags, and current location
- spaces: Spaces with categories, tags, and home location
- categories: Category hierarchy with parent references
- tags: Tags with display names
- contacts: Contact information with addresses
- groups: Groups with permissions
**Features:**
- Multi-language translation columns for each tenant language
- Column descriptions as Excel comments
- Example row if dataset is empty
- Pagination support for large datasets
**Export Limits:**
- Maximum 10,000 rows per export
- Use offset parameter for pagination
📤 RESPONSE 200
Inline Schema
Response: Binary file download (xlsx, csv, or tsv)
Schema: Binary file download (xlsx, csv, or tsv)
{
"description": "Binary file download (xlsx, csv, or tsv)",
"type": "string",
"format": "binary"
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/export/
List available export types
Returns a list of entity types that can be exported.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
]
}
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xlsx",
"csv",
"tsv"
]
}
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/import/{entityType}
Import entities from Excel/CSV/TSV file
Import entities of the specified type from an Excel (xlsx/xls), CSV, or TSV file.
**Supported Entity Types:**
- resources: Resources with categories, tags, and location
- spaces: Spaces with categories, tags, and home location
- categories: Category hierarchy with parent references
- tags: Tags with display names
- contacts: Contact information with addresses
- groups: Groups with permissions
**Import Options (multipart form field: options):**
- dryRun: Validate without saving (default: false)
- mergeStrategy: skip | replace | merge (default: skip)
- defaultTypeDefinitionId: Default type for new entities
- defaultCategoryId: Default category for new entities
- skipErrors: Continue on row errors (default: true)
- createMissingTags: Create tags that don't exist (default: false)
**File Requirements:**
- Maximum file size: 10MB
- Maximum rows: 10,000
- Header row required
- Supported formats: xlsx, xls, csv, tsv
**Column Handling:**
- Empty 'id' column: Create new entity
- Valid UUID in 'id': Update existing entity
- Translation columns: name_de, description_fr, etc.
- Categories: Comma-separated keys or names
- Tags: Comma-separated names
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/import/
List available import types and options
Returns a list of entity types that can be imported and available options.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
]
}
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xlsx",
"xls",
"csv",
"tsv"
]
}
},
"mergeStrategies": {
"type": "array",
"items": {
"type": "string",
"enum": [
"skip",
"replace",
"merge"
]
}
},
"maxFileSizeMB": {
"type": "number"
},
"maxRows": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/import/{entityType}/validate
Validate import file (dry run)
Validates the import file without saving any data. Use this endpoint to check for errors before actual import.
Returns the same result format as the import endpoint, with dryRun: true.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
External APIs
GET
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Integration control-plane tenant overrides list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"operation_key",
"operation_name",
"enabled",
"preferred_provider_order",
"quota_ceiling",
"override_config",
"updated_at"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
PUT
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Upsert integration control-plane tenant override
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"tenant_id",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"enabled",
"customer_credentials",
"quota_ceiling",
"preferred_provider_order",
"override_config",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
DELETE
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides/{id}
Delete integration control-plane tenant override
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deleted": {
"type": "boolean"
}
},
"required": [
"id",
"deleted"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations
Integration control-plane operations list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"operation_domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"system_scoped": {
"type": "boolean"
},
"request_count_24h": {
"type": "number"
},
"failure_count_24h": {
"type": "number"
}
},
"required": [
"operation_key",
"operation_name",
"operation_domain",
"enabled",
"system_scoped",
"request_count_24h",
"failure_count_24h"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations/{operationKey}
Integration control-plane operation detail
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"operation": {
"type": "object",
"additionalProperties": true
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_logs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"operation",
"metrics",
"recent_logs"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/overview
Integration telemetry overview
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_requests_24h": {
"type": "number"
},
"success_requests_24h": {
"type": "number"
},
"failure_requests_24h": {
"type": "number"
},
"success_rate_24h": {
"type": "number"
},
"warning_state_events_24h": {
"type": "number"
},
"error_state_events_24h": {
"type": "number"
},
"health_status": {
"type": "object",
"properties": {
"active": {
"type": "number"
},
"degraded": {
"type": "number"
},
"offline": {
"type": "number"
},
"error": {
"type": "number"
},
"unknown": {
"type": "number"
}
},
"required": [
"active",
"degraded",
"offline",
"error",
"unknown"
]
}
},
"required": [
"total_requests_24h",
"success_requests_24h",
"failure_requests_24h",
"success_rate_24h",
"warning_state_events_24h",
"error_state_events_24h",
"health_status"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/metrics
Integration hourly metrics
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/state
Integration state events
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"recent_failures": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_state_alerts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"latest_health_checks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"recent_failures",
"recent_state_alerts",
"latest_health_checks"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
Features
GET
/api/v1/secure/features/
No summary
List all features for current tenant with their status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"feature_key",
"enabled",
"config",
"definition"
],
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/{key}
No summary
Get status of a specific feature
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"feature_key",
"enabled",
"config",
"definition"
],
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/features/{key}
No summary
Enable or disable a feature (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether to enable or disable the feature"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Feature-specific configuration"
},
"changed_reason": {
"type": "string",
"description": "Reason for the change (audit trail)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"feature_key",
"enabled",
"config",
"definition"
],
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/features/bulk
No summary
Bulk enable/disable features (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"updates"
],
"properties": {
"updates": {
"type": "array",
"items": {
"type": "object",
"required": [
"feature_key",
"enabled"
],
"properties": {
"feature_key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"changed_reason": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"feature_key",
"enabled",
"config",
"definition"
],
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/catalog
No summary
Get catalog of all available features (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Feedback
POST
/api/v1/secure/feedback/rating
No summary
Submit a rating for an entity (resource, space, booking, app)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entityType",
"entityId",
"ratingType",
"value"
],
"properties": {
"entityType": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"ratingType": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/secure/feedback/rating/{id}
No summary
Update an existing rating
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"value": {
"type": "number"
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/feedback/rating/{id}
No summary
Delete an existing rating (and its reviews)
📤 RESPONSE 204
Rating deleted successfully
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/feedback/review
No summary
Submit a review linked to a rating
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ratingId",
"content"
],
"properties": {
"ratingId": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string",
"minLength": 10,
"maxLength": 5000
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/secure/feedback/review/{id}
No summary
Update an existing review
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"content": {
"type": "string",
"minLength": 10,
"maxLength": 5000
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/feedback/review/{id}
No summary
Delete an existing review
📤 RESPONSE 204
Review deleted successfully
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/feedback/review/{id}/flag
No summary
Flag a review for moderation (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"reason"
],
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/feedback/{entityType}/{entityId}/ratings
No summary
Get all ratings for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/feedback/{entityType}/{entityId}/reviews
No summary
Get all reviews for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/feedback/{entityType}/{entityId}/aggregates
No summary
Get rating aggregates (average, count, distribution) for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"total_count": {
"type": "number"
},
"average_rating": {
"type": "number"
},
"distribution": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Rating value -> count mapping"
},
"public_count": {
"type": "number"
},
"private_count": {
"type": "number"
}
},
"required": [
"entity_type",
"entity_id",
"rating_type",
"total_count",
"average_rating",
"distribution",
"public_count",
"private_count"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Files
POST
/api/v1/secure/files/upload
No summary
Upload file with intelligent storage distribution
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"fileId": {
"type": "string",
"format": "uuid"
},
"providerId": {
"type": "string",
"format": "uuid"
},
"providerPath": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string"
}
},
"required": [
"fileId",
"providerId",
"providerPath",
"publicUrl",
"sizeBytes"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/search
No summary
Search files with filters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string",
"nullable": true
},
"sizeBytes": {
"type": "number"
},
"spaceId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"providerId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"providerName": {
"type": "string"
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/statistics
No summary
Get file statistics for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"totalFiles": {
"type": "number"
},
"totalSizeBytes": {
"type": "number"
},
"byContentType": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"additionalProperties": false
}
},
"byProvider": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/{fileId}/download
No summary
Download file by ID
📤 RESPONSE 200
Inline Schema
Response: File stream
Schema: File stream
{
"type": "string",
"format": "binary",
"description": "File stream"
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/{fileId}
No summary
Get file metadata
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"providerId": {
"type": "string",
"format": "uuid"
},
"providerPath": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/{fileId}
No summary
Delete file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/{fileId}/move
No summary
Move file to different storage provider
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"targetProviderId"
],
"properties": {
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/
No summary
Create a bulk file migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"fileIds",
"targetProviderId"
],
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "File IDs to migrate"
},
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/
No summary
List file migration jobs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/{jobId}
No summary
Get migration job details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/migrations/{jobId}
No summary
Cancel a migration job
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/{jobId}/start
No summary
Start processing a migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Maximum concurrent file migrations"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Geo-Location
POST
/api/v1/secure/geo/geocode
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"anyOf": [
{
"required": [
"address"
]
},
{
"required": [
"structured"
]
}
],
"properties": {
"address": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"structured": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"formatted_address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"country_code": {
"type": "string"
}
}
},
"display_name": {
"type": "string"
},
"confidence": {
"type": "number"
},
"provider": {
"type": "string"
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/geo/reverse
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"zoom": {
"type": "number",
"minimum": 1,
"maximum": 18
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"formatted_address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"country_code": {
"type": "string"
}
}
},
"display_name": {
"type": "string"
},
"provider": {
"type": "string"
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/autocomplete
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"display_name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"type": {
"type": "string"
},
"importance": {
"type": "number"
}
}
}
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/config
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/geo/config
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"locale",
"format_type",
"address_template",
"component_order"
],
"properties": {
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string",
"minLength": 1
},
"component_order": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"separator": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/geo/config
Delete geo display config
Delete a display configuration for the current tenant
📤 RESPONSE 204
Successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/configs
Get batch geo configs
Get display configurations for multiple locales in one call
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"tenant_id",
"locale",
"format_type",
"address_template",
"component_order",
"separator",
"created_at",
"updated_at"
]
},
"description": "Map of locale codes to config objects"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Group Members
POST
/api/v1/secure/groups/{id}/members
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/groups/{id}/members
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"user_id",
"email",
"created_at"
]
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/groups/{id}/members/{userId}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Groups
GET
/api/v1/secure/groups/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/groups/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PUT
/api/v1/secure/groups/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/groups/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/groups/create
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/groups/export
No summary
Export groups to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/groups/import
No summary
Import groups from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Identity
GET
/api/v1/secure/auth/identities
List linked identities
Returns all OAuth providers linked to the current user account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"email": {
"type": "string",
"format": "email",
"nullable": true
},
"display_name": {
"type": "string",
"nullable": true
},
"avatar_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"linked_at": {
"type": "string",
"format": "date-time"
},
"last_login_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"is_primary": {
"type": "boolean",
"description": "Whether this is the primary login method"
}
},
"required": [
"id",
"provider",
"linked_at"
],
"additionalProperties": false
}
},
"email_auth_enabled": {
"type": "boolean",
"description": "Whether email/password authentication is enabled for this user"
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"email_auth_enabled",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/link/{provider}
Link OAuth provider
Initiates OAuth flow to link a new provider to the current account
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"redirectUrl": {
"type": "string",
"format": "uri",
"description": "URL to redirect to after OAuth linking completes"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "OAuth authorization URL for linking"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
}
},
"required": [
"url",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/auth/unlink/{provider}
Unlink OAuth provider
Removes a linked OAuth provider from the current account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
}
},
"required": [
"success",
"message",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/auth/primary/{provider}
Set primary provider
Sets the primary login method for the account
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"primary_provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github",
"email"
]
}
},
"required": [
"success",
"message",
"primary_provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/oauth-history
Get OAuth login history
Returns recent OAuth login attempts for the current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string"
},
"success": {
"type": "boolean"
},
"attempted_at": {
"type": "string",
"format": "date-time"
},
"ip_address": {
"type": "string",
"nullable": true
}
}
}
},
"total": {
"type": "integer"
}
},
"required": [
"data",
"total"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Integration Control Plane
GET
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Integration control-plane tenant overrides list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"operation_key",
"operation_name",
"enabled",
"preferred_provider_order",
"quota_ceiling",
"override_config",
"updated_at"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
PUT
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides
Upsert integration control-plane tenant override
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"tenant_id",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"customer_credentials": {
"type": "object",
"additionalProperties": true
},
"quota_ceiling": {
"type": "object",
"additionalProperties": true
},
"preferred_provider_order": {
"type": "array",
"items": {
"type": "string"
}
},
"override_config": {
"type": "object",
"additionalProperties": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation_id",
"enabled",
"customer_credentials",
"quota_ceiling",
"preferred_provider_order",
"override_config",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
DELETE
/api/v1/secure/admin/external-apis/control-plane/tenant-overrides/{id}
Delete integration control-plane tenant override
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deleted": {
"type": "boolean"
}
},
"required": [
"id",
"deleted"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations
Integration control-plane operations list
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation_key": {
"type": "string"
},
"operation_name": {
"type": "string"
},
"operation_domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"system_scoped": {
"type": "boolean"
},
"request_count_24h": {
"type": "number"
},
"failure_count_24h": {
"type": "number"
}
},
"required": [
"operation_key",
"operation_name",
"operation_domain",
"enabled",
"system_scoped",
"request_count_24h",
"failure_count_24h"
]
}
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/operations/{operationKey}
Integration control-plane operation detail
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"operation": {
"type": "object",
"additionalProperties": true
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_logs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"operation",
"metrics",
"recent_logs"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/overview
Integration telemetry overview
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_requests_24h": {
"type": "number"
},
"success_requests_24h": {
"type": "number"
},
"failure_requests_24h": {
"type": "number"
},
"success_rate_24h": {
"type": "number"
},
"warning_state_events_24h": {
"type": "number"
},
"error_state_events_24h": {
"type": "number"
},
"health_status": {
"type": "object",
"properties": {
"active": {
"type": "number"
},
"degraded": {
"type": "number"
},
"offline": {
"type": "number"
},
"error": {
"type": "number"
},
"unknown": {
"type": "number"
}
},
"required": [
"active",
"degraded",
"offline",
"error",
"unknown"
]
}
},
"required": [
"total_requests_24h",
"success_requests_24h",
"failure_requests_24h",
"success_rate_24h",
"warning_state_events_24h",
"error_state_events_24h",
"health_status"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/metrics
Integration hourly metrics
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/state
Integration state events
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"recent_failures": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"recent_state_alerts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"latest_health_checks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"recent_failures",
"recent_state_alerts",
"latest_health_checks"
]
}
},
"required": [
"data"
],
"response": {
"400": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"401": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"403": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"404": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"422": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
},
"500": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error code (e.g., AUTHENTICATION_ERROR, VALIDATION_ERROR)",
"examples": [
"AUTHENTICATION_ERROR",
"NOT_FOUND",
"VALIDATION_ERROR"
]
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code",
"examples": [
400,
401,
403,
404,
422,
500
]
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (e.g., validation errors)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of when error occurred"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}
}
}
Invitations
POST
/api/v1/public/invitations/validate
Validate invitation code
Check if an invitation code is valid and get invitation details
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Invitation code to validate"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"invitation": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
},
"error": {
"type": "string",
"nullable": true
}
},
"required": [
"valid"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/invitations/accept
Accept invitation
Accept an invitation and create a new user account (or link to existing via OAuth)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Invitation code"
},
"email": {
"type": "string",
"format": "email",
"description": "Email for new account (must match invitation if email-based)"
},
"password": {
"type": "string",
"minLength": 8,
"description": "Password for new account (required for password auth)"
},
"display_name": {
"type": "string",
"description": "Display name for new account"
},
"oauth_access_token": {
"type": "string",
"description": "OAuth access token (for social login registration)"
},
"oauth_refresh_token": {
"type": "string",
"description": "OAuth refresh token (for social login registration)"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenant_id",
"tenant_name",
"role"
]
},
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"requires_post_auth_flow": {
"type": "boolean"
}
},
"required": [
"success",
"message",
"user",
"access_token",
"refresh_token"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/invitations/
Create invitation
Create a new invitation to join the tenant. Sends invitation message via specified channel.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"recipient_email": {
"type": "string",
"format": "email",
"description": "Email address of the invited user"
},
"recipient_phone": {
"type": "string",
"description": "Phone number of the invited user (E.164 format)"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
],
"default": "member",
"description": "Role to assign to user upon accepting invitation"
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
],
"default": "email",
"description": "Delivery channel for invitation message"
},
"language": {
"type": "string",
"default": "en",
"description": "Language for invitation message (ISO 639-1 code)"
},
"personal_message": {
"type": "string",
"maxLength": 500,
"description": "Optional personal message from inviter"
},
"expires_in_hours": {
"type": "number",
"minimum": 1,
"maximum": 168,
"default": 24,
"description": "Hours until invitation expires"
}
},
"anyOf": [
{
"required": [
"recipient_email"
]
},
{
"required": [
"recipient_phone"
]
}
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"invited_by": {
"type": "string",
"format": "uuid"
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"code": {
"type": "string",
"description": "Masked code (last 4 chars visible)"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"sent",
"opened",
"accepted",
"expired",
"revoked",
"failed"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
]
},
"language": {
"type": "string"
},
"personal_message": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"sent_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"opened_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"invitation_url": {
"type": "string",
"format": "uri",
"description": "Full invitation URL for the recipient"
},
"full_code": {
"type": "string",
"description": "Full invitation code (only shown once on creation)"
}
},
"required": [
"id",
"tenant_id",
"invited_by",
"role",
"status",
"channel",
"language",
"expires_at",
"created_at",
"updated_at",
"invitation_url",
"full_code"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/invitations/
List invitations
List all invitations for the current tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"invited_by": {
"type": "string",
"format": "uuid"
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"code": {
"type": "string",
"description": "Masked code (last 4 chars visible)"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"sent",
"opened",
"accepted",
"expired",
"revoked",
"failed"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
]
},
"language": {
"type": "string"
},
"personal_message": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"sent_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"opened_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"invited_by",
"role",
"status",
"channel",
"language",
"expires_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/invitations/{id}
Get invitation
Get details of a specific invitation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"invited_by": {
"type": "string",
"format": "uuid"
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"code": {
"type": "string",
"description": "Masked code (last 4 chars visible)"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"sent",
"opened",
"accepted",
"expired",
"revoked",
"failed"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
]
},
"language": {
"type": "string"
},
"personal_message": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"sent_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"opened_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"invited_by",
"role",
"status",
"channel",
"language",
"expires_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/invitations/{id}
Revoke invitation
Cancel/revoke a pending invitation
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/invitations/{id}/resend
Resend invitation
Resend an invitation message, optionally changing channel or extending expiry
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
],
"description": "Optionally change delivery channel"
},
"language": {
"type": "string",
"description": "Optionally change language"
},
"extend_expiry": {
"type": "boolean",
"default": true,
"description": "Reset expiry to 24h from now"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"invited_by": {
"type": "string",
"format": "uuid"
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"code": {
"type": "string",
"description": "Masked code (last 4 chars visible)"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"sent",
"opened",
"accepted",
"expired",
"revoked",
"failed"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp"
]
},
"language": {
"type": "string"
},
"personal_message": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"sent_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"opened_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"accepted_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"invited_by",
"role",
"status",
"channel",
"language",
"expires_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Jobs
GET
/api/v1/secure/jobs/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Unique job identifier"
},
"displayName": {
"type": "string",
"description": "Human-readable name"
},
"description": {
"type": "string",
"description": "Job description"
},
"schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Cron expression"
},
"scheduleDescription": {
"type": "string",
"description": "Human-readable schedule"
},
"category": {
"type": "string",
"enum": [
"cleanup",
"maintenance",
"messaging",
"metrics",
"media",
"custom"
],
"description": "Job category"
},
"isSystem": {
"type": "boolean",
"description": "Whether this is a system job"
},
"isActive": {
"type": "boolean",
"description": "Whether job is currently active"
},
"lastRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Last execution time"
},
"nextRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Next scheduled run"
},
"environment": {
"type": "string",
"enum": [
"pg_boss",
"pg_cron",
"both"
],
"description": "Execution environment"
},
"retryConfig": {
"type": "object",
"properties": {
"limit": {
"type": "number"
},
"delaySeconds": {
"type": "number"
},
"backoff": {
"type": "boolean"
}
},
"description": "Retry configuration"
},
"enabled": {
"type": "boolean",
"description": "Deprecated: use isActive"
}
},
"required": [
"name",
"isSystem"
],
"additionalProperties": true
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/registry
No summary
Get job registry with all job definitions and configurations
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string"
},
"schedule": {
"type": "string"
},
"scheduleDescription": {
"type": "string"
},
"environment": {
"type": "string"
},
"isSystem": {
"type": "boolean"
},
"enabledByDefault": {
"type": "boolean"
},
"retry": {
"type": "object",
"properties": {
"limit": {
"type": "number"
},
"delaySeconds": {
"type": "number"
},
"backoff": {
"type": "boolean"
}
}
},
"sqlFunction": {
"type": "string",
"nullable": true
},
"timeoutSeconds": {
"type": "number"
}
}
}
},
"summary": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"scheduled": {
"type": "number"
},
"eventDriven": {
"type": "number"
},
"byCategory": {
"type": "object"
},
"byEnvironment": {
"type": "object"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/{name}/status
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"nextRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"isSystem": {
"type": "boolean"
},
"runCount": {
"type": "number"
},
"successCount": {
"type": "number"
},
"failureCount": {
"type": "number"
},
"avgDurationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/active
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"jobName": {
"type": "string"
},
"tenantId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startedAt": {
"type": "string"
},
"correlationId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/{name}/history
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"job_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"running",
"completed",
"failed",
"cancelled"
]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"correlation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/history
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"job_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"running",
"completed",
"failed",
"cancelled"
]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"duration_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenant_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"correlation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/jobs/{name}/trigger
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
},
"tenantId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/jobs/{name}/{jobId}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"cancelled": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/jobs/{name}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/notifications/settings
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"emailRecipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"notifyOnSuccess": {
"type": "boolean"
},
"notifyOnFailure": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/jobs/notifications/settings
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"jobName"
],
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"notify_on_failure": {
"type": "boolean"
},
"notify_on_completion": {
"type": "boolean"
},
"notify_on_long_running": {
"type": "boolean"
},
"long_running_threshold_ms": {
"type": "number"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"emailRecipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"notifyOnSuccess": {
"type": "boolean"
},
"notifyOnFailure": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Languages (Public)
GET
/api/v1/public/languages/
List all languages with optional filters and prioritization
Get all languages with optional search, prioritization, and country-specific filtering.
**Prioritization Logic:**
- Default priority languages: de, fr, it, es (shown first)
- If countryCode provided: adds country-specific languages + en to top
- Example: ?countryCode=CH → de,fr,it,rm,en appear first
**Supported Country Codes:** CH, DE, FR, IT, ES, US, GB, TH, JP, CN, KR
No tenant isolation - same data for all tenants.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"languages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"iso_code_1": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "ISO 639-1 two-letter language code (lowercase)",
"example": "en"
},
"iso_code_2": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-2 three-letter language code (lowercase)",
"example": "eng"
},
"iso_code_3": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-3 three-letter language code (lowercase, alternative)",
"example": "eng"
},
"name_english": {
"type": "string",
"description": "English name of the language (international standard)",
"example": "English"
},
"name_local": {
"type": "string",
"description": "Native name in language's own script (UTF-8)",
"example": "English"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"nullable": true,
"description": "ISO 3166-1 alpha-2 country code for flag display",
"example": "GB"
},
"metadata": {
"type": "object",
"properties": {
"script": {
"type": "string",
"example": "Latin"
},
"language_family": {
"type": "string",
"example": "Germanic"
},
"speakers_millions": {
"type": "number",
"example": 1500
}
},
"additionalProperties": true,
"description": "Additional metadata (script, language family, speaker count, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when language was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when language was last updated"
}
},
"required": [
"iso_code_1",
"name_english",
"name_local",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of languages matching filters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"description": "Maximum number of results per page"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of results skipped (pagination offset)"
}
},
"required": [
"languages",
"total",
"limit",
"offset"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/languages/{code}
Get language by ISO code
Get single language by ISO 639-1, 639-2, or 639-3 code.
**Supported Code Formats:**
- ISO 639-1 (2 chars): en, de, ko, th
- ISO 639-2 (3 chars): eng, deu, kor, tha
- ISO 639-3 (3 chars): eng, deu, kor, tha
Returns name_english (e.g., "Korean") and name_local (e.g., "한국어").
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"iso_code_1": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "ISO 639-1 two-letter language code (lowercase)",
"example": "en"
},
"iso_code_2": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-2 three-letter language code (lowercase)",
"example": "eng"
},
"iso_code_3": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-3 three-letter language code (lowercase, alternative)",
"example": "eng"
},
"name_english": {
"type": "string",
"description": "English name of the language (international standard)",
"example": "English"
},
"name_local": {
"type": "string",
"description": "Native name in language's own script (UTF-8)",
"example": "English"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"nullable": true,
"description": "ISO 3166-1 alpha-2 country code for flag display",
"example": "GB"
},
"metadata": {
"type": "object",
"properties": {
"script": {
"type": "string",
"example": "Latin"
},
"language_family": {
"type": "string",
"example": "Germanic"
},
"speakers_millions": {
"type": "number",
"example": 1500
}
},
"additionalProperties": true,
"description": "Additional metadata (script, language family, speaker count, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when language was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when language was last updated"
}
},
"required": [
"iso_code_1",
"name_english",
"name_local",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Lifecycle
POST
/api/v1/secure/tenants/{id}/lifecycle/activate
No summary
Activate tenant (pending → trial, or inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for activation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/upgrade
No summary
Upgrade tenant type (trial → paid → enterprise)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"target_type"
],
"properties": {
"target_type": {
"type": "string",
"enum": [
"paid",
"enterprise"
],
"description": "Target plan type"
},
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for upgrade (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/suspend
No summary
Suspend tenant (active → inactive)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for suspension (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/reactivate
No summary
Reactivate tenant (inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for reactivation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/archive
No summary
Archive tenant (inactive → retired)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for archiving (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/lifecycle/history
No summary
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"from_status": {
"type": "string"
},
"to_status": {
"type": "string"
},
"from_type": {
"type": "string"
},
"to_type": {
"type": "string"
},
"action": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"performed_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"from_status",
"to_status",
"action",
"performed_by",
"created_at"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Logs
GET
/api/v1/system/logs/
Query historical logs
System admin only. Query and filter application logs with pagination.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"level": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
},
"message": {
"type": "string"
},
"service": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"userId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"requestId": {
"type": "string",
"nullable": true
},
"context": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"timestamp",
"level",
"message"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/analytics
Get log analytics
System admin only. Get error rates, charts, and performance metrics.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"errorRate": {
"type": "number"
},
"errorCount": {
"type": "number"
},
"totalRequests": {
"type": "number"
},
"responseTime": {
"type": "object",
"properties": {
"p50": {
"type": "number"
},
"p95": {
"type": "number"
},
"p99": {
"type": "number"
}
},
"additionalProperties": false
},
"topErrors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"count": {
"type": "number"
},
"lastOccurrence": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"tenantActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"requestCount": {
"type": "number"
},
"errorCount": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/security-audit
Get security audit log
System admin only. Get security-related events (failed logins, permission denials, etc.).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"eventType": {
"type": "string",
"enum": [
"login_failed",
"permission_denied",
"api_key_used",
"admin_action"
]
},
"userId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/config
Get log configuration
System admin only. Get current log level configuration, formatting, and cleanup settings.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"description": "Per-service log levels",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"console": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"colorize": {
"type": "boolean"
},
"timestamp": {
"type": "boolean"
}
},
"additionalProperties": false
},
"database": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"table": {
"type": "string"
},
"batchSize": {
"type": "number"
},
"flushInterval": {
"type": "number"
}
},
"additionalProperties": false
},
"formatting": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"includeTimestamp": {
"type": "boolean"
},
"includeService": {
"type": "boolean"
},
"includeContext": {
"type": "boolean"
},
"redactSensitive": {
"type": "boolean"
}
},
"additionalProperties": false
},
"cleanup": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
},
"archiveEnabled": {
"type": "boolean"
},
"archiveLocation": {
"type": "string"
},
"cleanupSchedule": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/logs/config
Update log configuration
System admin only. Update log levels, formatting, and cleanup settings. Changes apply without restart.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"console": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"colorize": {
"type": "boolean"
},
"timestamp": {
"type": "boolean"
},
"levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
}
}
},
"database": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"table": {
"type": "string"
},
"batchSize": {
"type": "number",
"minimum": 1,
"maximum": 1000
},
"flushInterval": {
"type": "number",
"minimum": 1000,
"maximum": 60000
},
"levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
}
}
},
"formatting": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"json",
"pretty",
"compact"
]
},
"includeTimestamp": {
"type": "boolean"
},
"includeService": {
"type": "boolean"
},
"includeContext": {
"type": "boolean"
},
"redactSensitive": {
"type": "boolean"
}
}
},
"cleanup": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
},
"archiveEnabled": {
"type": "boolean"
},
"archiveLocation": {
"type": "string"
},
"cleanupSchedule": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"applied": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/config/{section}
Get section configuration
System admin only. Get configuration for a specific section.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/logs/config/{section}
Update section configuration
System admin only. Update configuration for a specific section. Changes apply without restart.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"additionalProperties": true
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"applied": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/validate
Validate log configuration
System admin only. Validate configuration before saving. Returns errors and warnings.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"section": {
"type": "string",
"enum": [
"console",
"database",
"formatting",
"cleanup",
"log-levels"
]
},
"config": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"config"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/preview
Preview configuration changes
System admin only. Preview affected services and impact of configuration changes (AC15 requirement).
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"logLevels": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
}
},
"cleanup": {
"type": "object",
"properties": {
"retentionDays": {
"type": "number",
"enum": [
30,
60,
90
]
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"affectedServices": {
"type": "array",
"items": {
"type": "string"
}
},
"estimatedLogVolume": {
"type": "number"
},
"storageImpact": {
"type": "object",
"properties": {
"current": {
"type": "number"
},
"projected": {
"type": "number"
},
"change": {
"type": "number"
}
},
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/export
Export logs to storage
System admin only. Export logs to pve-system storage bucket for archiving or analysis.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"startTime": {
"type": "string",
"format": "date-time"
},
"endTime": {
"type": "string",
"format": "date-time"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"level": {
"type": "string",
"enum": [
"trace",
"debug",
"info",
"warn",
"error",
"fatal"
]
},
"format": {
"type": "string",
"enum": [
"json",
"csv"
],
"default": "json"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"path": {
"type": "string"
},
"recordCount": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"required": [
"message",
"path",
"recordCount",
"sizeBytes"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/exports
List log exports
System admin only. List available log export files in storage.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"size": {
"type": "number"
},
"createdAt": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/logs/exports/{filename}
Delete log export
System admin only. Delete a log export file from storage.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"deleted": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/logs/config/reset
Reset log configuration to defaults
System admin only. Reset all log settings to default values.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"reset": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
MCP
GET
/mcp/setup
MCP server setup guide
Interactive setup guide for connecting Cursor, VS Code, Windsurf, Claude Desktop, and other MCP clients to this server.
📤 RESPONSE 200
Default Response
GET
/mcp/info
MCP server information
Returns metadata about the PVE Platform MCP server including available tool categories and protocol details.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"protocol": {
"type": "string"
},
"specVersion": {
"type": "string"
},
"endpoint": {
"type": "string"
},
"transport": {
"type": "string"
},
"serverName": {
"type": "string"
},
"tools": {
"type": "object",
"properties": {
"public": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"tools": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"authenticated": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"tools": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
Media
POST
/api/v1/services/media/upload
No summary
Upload media file with multipart/form-data
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/services/media/{id}
No summary
📤 RESPONSE 204
Media file deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/{id}/versions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"media_file_id",
"version",
"storage_path",
"public_url",
"file_size_bytes",
"mime_type",
"uploaded_at",
"uploaded_by",
"metadata"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"mime_type": {
"type": "string"
},
"uploaded_at": {
"type": "string",
"format": "date-time"
},
"uploaded_by": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "File metadata (EXIF, dimensions, etc.)"
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/media/{id}/geo-tag
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/media/{id}/thumbnails/regenerate
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"version": {
"type": "number",
"minimum": 1
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"thumbnails": {
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"media_file_id",
"version",
"thumbnails"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/{id}/thumbnails
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"thumbnails": {
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"media_file_id",
"version",
"thumbnails"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/{id}/links
No summary
Get all entities linked to this media file (reverse lookup)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"links",
"total"
],
"properties": {
"links": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"entity_type",
"entity_id",
"entity_name",
"is_main",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Link ID"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource",
"contact",
"tenant"
],
"description": "Type of entity linked to this media"
},
"entity_id": {
"type": "string",
"format": "uuid",
"description": "ID of the linked entity"
},
"entity_name": {
"type": "string",
"description": "Display name of the linked entity"
},
"is_main": {
"type": "boolean",
"description": "Whether this is the main/profile image for the entity"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the link was created"
}
}
},
"description": "List of entities linked to this media file"
},
"total": {
"type": "number",
"minimum": 0,
"description": "Total number of linked entities"
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/media/entity/{entityType}/{entityId}/media
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"media_file_id"
],
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number",
"minimum": 0
},
"public_display": {
"type": "boolean"
},
"display_from": {
"type": "string",
"format": "date-time"
},
"display_until": {
"type": "string",
"format": "date-time"
},
"caption": {
"type": "string",
"maxLength": 1000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/entity/{entityType}/{entityId}/media
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/media/entity/{entityType}/{entityId}/media/main
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number",
"minimum": 0
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}
No summary
📤 RESPONSE 204
Media unlinked successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}/main
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/services/media/entity/{entityType}/{entityId}/media/reorder
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"reorder"
],
"properties": {
"reorder": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"sort_order"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"sort_order": {
"type": "number",
"minimum": 0
}
}
},
"minItems": 1
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Messaging
POST
/api/v1/services/messaging/send
No summary
Queue a message for delivery via email, SMS, WhatsApp, or webhook
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
],
"description": "Delivery channel"
},
"recipient_email": {
"type": "string",
"format": "email",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"recipient_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"template_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"template_name": {
"type": "string",
"nullable": true
},
"subject": {
"type": "string",
"nullable": true
},
"content": {
"type": "string",
"nullable": true
},
"variables": {
"type": "object",
"additionalProperties": true,
"nullable": true
}
},
"required": [
"channel"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"channel": {
"type": "string"
},
"created_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/{id}/status
No summary
Get delivery status and tracking info for a specific message
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"channel": {
"type": "string"
},
"retry_count": {
"type": "number"
},
"max_retries": {
"type": "number"
},
"next_retry_at": {
"type": "string",
"nullable": true
},
"last_error": {
"type": "string",
"nullable": true
},
"provider_message_id": {
"type": "string",
"nullable": true
},
"provider_response": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"sent_at": {
"type": "string",
"nullable": true
},
"delivered_at": {
"type": "string",
"nullable": true
},
"opened_at": {
"type": "string",
"nullable": true
},
"clicked_at": {
"type": "string",
"nullable": true
},
"bounced_at": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/{id}/provider-logs
No summary
Get provider interaction logs for a specific message (attempts, errors, responses)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"message_id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string",
"description": "Provider name: sendgrid, mail2sms, twilio, webhook"
},
"channel": {
"type": "string",
"description": "Channel: email, sms, whatsapp, webhook"
},
"recipient": {
"type": "string",
"nullable": true
},
"event_type": {
"type": "string",
"enum": [
"attempt",
"success",
"failure",
"retry",
"config_error",
"provider_error"
],
"description": "Type of provider interaction event"
},
"attempt_number": {
"type": "integer",
"description": "Retry attempt number"
},
"success": {
"type": "boolean",
"nullable": true,
"description": "Whether the API call succeeded"
},
"status_code": {
"type": "integer",
"nullable": true,
"description": "HTTP status code from provider"
},
"provider_message_id": {
"type": "string",
"nullable": true,
"description": "Message ID returned by provider"
},
"response_data": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Full provider API response for debugging"
},
"error_message": {
"type": "string",
"nullable": true,
"description": "Error message if failed"
},
"error_details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Detailed error information from provider"
},
"duration_ms": {
"type": "integer",
"nullable": true,
"description": "API call duration in milliseconds"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"provider",
"channel",
"event_type",
"attempt_number",
"created_at"
]
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/{id}/retry
No summary
Retry a failed or stuck message by resetting it to queued status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"status": {
"type": "string",
"description": "New message status after action"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/{id}/cancel
No summary
Cancel a pending message (only works for queued messages)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"status": {
"type": "string",
"description": "New message status after action"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/preview
No summary
Preview a rendered message template with variables without sending it
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"template_id",
"variables"
],
"properties": {
"template_id": {
"type": "string",
"format": "uuid"
},
"variables": {
"type": "object"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"nullable": true
},
"content": {
"type": "string"
},
"variables_used": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/templates
No summary
List available message templates, optionally filtered by channel and/or language
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string"
},
"version": {
"type": "number"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"description": "ISO language code"
},
"subject": {
"type": [
"null",
"string"
],
"description": "Email subject (for email channel)"
},
"content": {
"type": "string",
"description": "Template content with {{variables}}"
}
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/templates
No summary
Create a new message template
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"channel",
"content",
"variables"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
"description": "ISO language code (e.g., en, de, fr). Defaults to en."
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string"
},
"version": {
"type": "number"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"description": "ISO language code"
},
"subject": {
"type": [
"null",
"string"
],
"description": "Email subject (for email channel)"
},
"content": {
"type": "string",
"description": "Template content with {{variables}}"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/stats
No summary
Get messaging statistics for the tenant (counts by status)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_messages": {
"type": "number"
},
"queued": {
"type": "number"
},
"sent": {
"type": "number"
},
"delivered": {
"type": "number"
},
"failed": {
"type": "number"
},
"bounced": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/recent
No summary
List recent messages sent by the tenant with optional limit
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"channel": {
"type": "string"
},
"status": {
"type": "string"
},
"subject": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"sent_at": {
"type": "string",
"nullable": true
},
"retry_count": {
"type": "number"
},
"max_retries": {
"type": "number"
},
"next_retry_at": {
"type": "string",
"nullable": true
},
"last_error": {
"type": "string",
"nullable": true
},
"provider_message_id": {
"type": "string",
"nullable": true
},
"provider_response": {
"type": "object",
"nullable": true,
"additionalProperties": true
}
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/services/messaging/templates/{id}
No summary
Update a message template (creates new version)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"description": {
"type": "string"
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string"
},
"version": {
"type": "number"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"description": "ISO language code"
},
"subject": {
"type": [
"null",
"string"
],
"description": "Email subject (for email channel)"
},
"content": {
"type": "string",
"description": "Template content with {{variables}}"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/services/messaging/templates/{id}
No summary
Delete a message template (deactivates all versions)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/rate-limits
No summary
Get current rate limiting statistics for message sending
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"stats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"activeSends": {
"type": "integer",
"description": "Currently active concurrent sends"
},
"sendsInWindow": {
"type": "integer",
"description": "Total sends in current 1-minute window"
},
"maxConcurrent": {
"type": "integer",
"description": "Maximum allowed concurrent sends"
},
"maxPerMinute": {
"type": "integer",
"description": "Maximum sends allowed per minute"
}
},
"required": [
"tenantId",
"channel",
"activeSends",
"sendsInWindow",
"maxConcurrent",
"maxPerMinute"
]
}
},
"defaultLimits": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer"
},
"maxPerMinute": {
"type": "integer"
}
}
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer"
},
"maxPerMinute": {
"type": "integer"
}
}
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer"
},
"maxPerMinute": {
"type": "integer"
}
}
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer"
},
"maxPerMinute": {
"type": "integer"
}
}
}
}
}
}
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/rate-limits/config
No summary
Get current rate limit configuration for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"config": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"defaults": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"isCustom": {
"type": "boolean",
"description": "Whether tenant has custom rate limits configured"
}
},
"required": [
"config",
"defaults",
"isCustom"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PUT
/api/v1/services/messaging/rate-limits/config
No summary
Update rate limit configuration for the tenant. Supports partial updates.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000
}
}
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000
}
}
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000
}
}
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000
}
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"config": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"defaults": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"isCustom": {
"type": "boolean",
"description": "Whether tenant has custom rate limits configured"
}
},
"required": [
"config",
"defaults",
"isCustom"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/services/messaging/rate-limits/config
No summary
Reset rate limit configuration to system defaults
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"config": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"defaults": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"sms": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"whatsapp": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
},
"webhook": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Maximum concurrent sends (semaphore slots)"
},
"maxPerMinute": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Maximum sends per minute per tenant"
},
"cooldownMs": {
"type": "integer",
"minimum": 100,
"maximum": 60000,
"description": "Cooldown period in milliseconds when limit is hit"
}
},
"required": [
"maxConcurrent",
"maxPerMinute",
"cooldownMs"
]
}
},
"additionalProperties": false
},
"isCustom": {
"type": "boolean",
"description": "Whether tenant has custom rate limits configured"
}
},
"required": [
"config",
"defaults",
"isCustom"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/templates/{id}/export
No summary
Export a single message template as JSON
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"null",
"string"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string"
},
"version": {
"type": "number"
}
},
"required": [
"name",
"channel",
"content",
"variables",
"language",
"version"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/messaging/templates/export
No summary
Export all message templates for the tenant as JSON bundle
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Bundle version (e.g., \"1.0\")"
},
"exportedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"tenantId"
]
},
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"null",
"string"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string"
},
"version": {
"type": "number"
}
},
"required": [
"name",
"channel",
"content",
"variables",
"language",
"version"
]
}
}
},
"required": [
"version",
"exportedAt",
"source",
"templates"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/services/messaging/templates/import
No summary
Import message templates from JSON. Supports individual templates or bundle format.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"templates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": [
"string",
"null"
]
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
}
},
"required": [
"name",
"channel",
"content"
]
}
},
"options": {
"type": "object",
"properties": {
"mergeStrategy": {
"type": "string",
"enum": [
"skip",
"replace",
"merge"
],
"default": "skip",
"description": "How to handle existing templates: skip (keep existing), replace (overwrite), merge (update only empty fields)"
},
"dryRun": {
"type": "boolean",
"default": false,
"description": "If true, validate without saving"
}
}
}
},
"required": [
"templates"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Template index in input array"
},
"name": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Migration
POST
/api/v1/secure/files/migrations/
No summary
Create a bulk file migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"fileIds",
"targetProviderId"
],
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "File IDs to migrate"
},
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/
No summary
List file migration jobs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/{jobId}
No summary
Get migration job details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/migrations/{jobId}
No summary
Cancel a migration job
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/{jobId}/start
No summary
Start processing a migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Maximum concurrent file migrations"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Multi-Tenant
GET
/api/v1/public/auth/user-tenants
Get user tenants by email
Returns list of tenants the user has access to. For security, always returns an empty list for non-existent users.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tenants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug"
]
}
},
"hasMultipleTenants": {
"type": "boolean"
}
},
"required": [
"tenants",
"hasMultipleTenants"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/auth/tenants
Get user tenants
Returns list of tenants the current user has access to
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"pending",
"invited"
]
},
"is_default": {
"type": "boolean"
},
"joined_at": {
"type": "string",
"format": "date-time"
},
"tenant_name": {
"type": "string"
},
"tenant_slug": {
"type": "string"
}
},
"required": [
"user_id",
"tenant_id",
"role",
"tenant_name",
"tenant_slug"
],
"additionalProperties": false
}
},
"active_tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"default_tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/switch-tenant
Switch tenant
Switch the active tenant for the current session
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Target tenant ID to switch to"
}
},
"required": [
"tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"tenant_slug": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"success",
"tenant_id",
"tenant_name",
"tenant_slug",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/auth/default-tenant
Set default tenant
Set the default tenant that will be used on login
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant ID to set as default"
}
},
"required": [
"tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"default_tenant_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"success",
"default_tenant_id"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/auth/leave-tenant/{tenantId}
Leave tenant
Remove yourself from a tenant membership
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/auth/tenant-role
Get tenant role
Get the current user's role in the active tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"tenant_id",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
OAuth
GET
/api/v1/public/auth/providers
Get enabled OAuth providers
Returns a list of OAuth providers that are enabled for authentication, along with tenant-specific settings
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"description": "Provider identifier"
},
"name": {
"type": "string",
"description": "Display name for the provider"
},
"enabled": {
"type": "boolean",
"description": "Whether this provider is enabled"
},
"icon": {
"type": "string",
"description": "Icon name or URL for the provider"
}
},
"required": [
"id",
"name",
"enabled"
],
"additionalProperties": false
},
"description": "List of available OAuth providers"
},
"emailEnabled": {
"type": "boolean",
"description": "Whether email/password login is enabled"
},
"tenantConfig": {
"type": "object",
"properties": {
"requireInvitation": {
"type": "boolean",
"description": "Whether users must have an invitation to register"
},
"allowSelfRegistration": {
"type": "boolean",
"description": "Whether users can self-register without invitation"
},
"passwordAuthEnabled": {
"type": "boolean",
"description": "Whether email/password authentication is enabled"
},
"mfaRequired": {
"type": "boolean",
"description": "Whether MFA is required for all users"
}
},
"required": [
"requireInvitation",
"allowSelfRegistration",
"passwordAuthEnabled",
"mfaRequired"
],
"additionalProperties": false,
"description": "Tenant-specific authentication configuration"
}
},
"required": [
"data",
"emailEnabled"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/oauth/init
Initiate OAuth flow
Starts OAuth authentication with the specified provider
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"description": "OAuth provider to authenticate with"
},
"redirectUrl": {
"type": "string",
"format": "uri",
"description": "URL to redirect to after authentication"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Optional tenant ID for multi-tenant login"
}
},
"required": [
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "OAuth provider authorization URL"
},
"provider": {
"type": "string",
"description": "The provider being used"
}
},
"required": [
"url",
"provider"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/oauth/register
Complete OAuth registration
Creates a platform account for an OAuth-authenticated user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"displayName": {
"type": "string"
},
"registrationMode": {
"type": "string",
"enum": [
"create_tenant",
"join_tenant",
"system_tenant"
]
},
"tenantName": {
"type": "string"
},
"tenantDomain": {
"type": "string"
},
"inviteCode": {
"type": "string"
},
"locale": {
"type": "string"
}
},
"required": [
"accessToken",
"refreshToken",
"registrationMode"
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"displayName": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"tenantName": {
"type": "string"
}
}
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"requiresPostAuthFlow": {
"type": "boolean"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Password Reset
POST
/api/v1/public/auth/forgot-password
Request password reset
Send password reset email to user. Always returns success for security.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/auth/validate-reset-token
Validate reset token
Check if a password reset token is valid and not expired
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"email": {
"type": "string",
"format": "email"
}
},
"required": [
"valid"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/reset-password
Reset password
Set new password using a valid reset token. Token is single-use.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"token",
"password"
],
"properties": {
"token": {
"type": "string",
"minLength": 1
},
"password": {
"type": "string",
"minLength": 8
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Phone Validation (Public)
POST
/api/v1/public/phone/validate
Validate phone number
Validate phone number format and return detailed information if valid
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41 79 123 45 67)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/phone/format
Format phone number
Format phone number in specified format
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41791234567)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
},
"format": {
"type": "string",
"enum": [
"E.164",
"INTERNATIONAL",
"NATIONAL",
"RFC3966"
],
"default": "E.164"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/phone/parse
Parse phone number
Parse phone number to extract components
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41 79 123 45 67)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/phone/region
Detect country from phone number
Auto-detect country code from phone number
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41791234567)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone/countries
Get supported countries
Get list of all ISO country codes supported by phone validation
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone/calling-code/{countryCode}
Get calling code for country
Get international calling code for a specific ISO country code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"description": "Whether the phone number is valid"
},
"formatted": {
"type": "string",
"description": "Formatted phone number in E.164 format"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country_name": {
"type": "string",
"description": "Full country name"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mobile carrier name (if available)"
},
"line_type": {
"anyOf": [
{
"type": "string",
"enum": [
"mobile",
"landline",
"voip",
"toll-free",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Type of phone line"
},
"location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Geographic location (if available)"
}
},
"required": [
"valid",
"formatted",
"country_code"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Profile
GET
/api/v1/secure/profile/avatar/sources
Get available avatar sources
Returns all available avatar sources including generated, uploaded, and OAuth provider avatars
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"currentSource": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Currently selected avatar source"
},
"currentIdentityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID if current source is remote"
},
"currentAvatarUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Current resolved avatar URL"
},
"availableSources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source type"
},
"previewUrl": {
"type": "string",
"format": "uri",
"description": "Preview URL for this avatar source"
},
"thumbnailUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Thumbnail URL (for uploaded avatars)"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID (for remote avatars)"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
],
"nullable": true,
"description": "OAuth provider (for remote avatars)"
},
"providerName": {
"type": "string",
"nullable": true,
"description": "Display name of the OAuth provider"
}
},
"required": [
"type",
"previewUrl"
],
"additionalProperties": false
},
"description": "All available avatar sources for this user"
}
},
"required": [
"currentSource",
"availableSources"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/profile/avatar/
Set avatar source
Sets the avatar source for the current user profile
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source to set"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID (required when source is \"remote\")"
}
},
"required": [
"source"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"source"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/profile/avatar/
Reset avatar
Resets the avatar to generated mode (initials-based)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"description": "Generated avatar URL"
}
},
"required": [
"source",
"avatarUrl"
]
}
},
"required": [
"success",
"message",
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/profile/avatar/
Get current avatar
Returns the current avatar source and URL for the user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
]
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"source"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Public
POST
/api/v1/public/invitations/validate
Validate invitation code
Check if an invitation code is valid and get invitation details
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Invitation code to validate"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"invitation": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"member",
"guest"
]
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"invited_by_name": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
},
"error": {
"type": "string",
"nullable": true
}
},
"required": [
"valid"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/invitations/accept
Accept invitation
Accept an invitation and create a new user account (or link to existing via OAuth)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Invitation code"
},
"email": {
"type": "string",
"format": "email",
"description": "Email for new account (must match invitation if email-based)"
},
"password": {
"type": "string",
"minLength": 8,
"description": "Password for new account (required for password auth)"
},
"display_name": {
"type": "string",
"description": "Display name for new account"
},
"oauth_access_token": {
"type": "string",
"description": "OAuth access token (for social login registration)"
},
"oauth_refresh_token": {
"type": "string",
"description": "OAuth refresh token (for social login registration)"
}
},
"required": [
"code"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"display_name": {
"type": "string",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenant_id",
"tenant_name",
"role"
]
},
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"requires_post_auth_flow": {
"type": "boolean"
}
},
"required": [
"success",
"message",
"user",
"access_token",
"refresh_token"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/qr/{uuid}
Public QR code embed
Get QR code image for embedding. Access depends on QR code access_level setting.
📤 RESPONSE 200
Inline Schema
Response: QR code image
Schema: QR code image
{
"description": "QR code image",
"type": "string",
"format": "binary"
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 429
- 429 Too Many Requests - Rate limit exceeded
→ See StandardErrorResponse
Note: 429 Too Many Requests - Rate limit exceeded
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
QR Codes
GET
/api/v1/secure/qr-codes/
List QR codes
Get paginated list of QR codes with optional filters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
},
"name": {
"type": "string",
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Whether versioning is enabled"
},
"versionCounter": {
"type": "integer",
"description": "Current version number"
},
"latestMediaId": {
"type": "string",
"format": "uuid",
"description": "Latest media file UUID"
},
"publicUrl": {
"type": "string",
"description": "Public URL for embedding (only if accessLevel is PUBLIC)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdBy": {
"type": "string",
"description": "Created by identifier"
},
"updatedBy": {
"type": "string",
"description": "Updated by identifier"
}
},
"required": [
"id",
"uuid",
"tenantId",
"createdByUserId",
"name",
"type",
"payloadTemplate",
"options",
"renderMode",
"accessLevel",
"isVersioned",
"versionCounter",
"createdAt",
"updatedAt"
]
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": [
"total",
"limit",
"offset"
]
}
},
"required": [
"data",
"pagination"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/qr-codes/
Create QR code
Create a new QR code
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Enable versioning"
}
},
"required": [
"name",
"type"
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
},
"name": {
"type": "string",
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Whether versioning is enabled"
},
"versionCounter": {
"type": "integer",
"description": "Current version number"
},
"latestMediaId": {
"type": "string",
"format": "uuid",
"description": "Latest media file UUID"
},
"publicUrl": {
"type": "string",
"description": "Public URL for embedding (only if accessLevel is PUBLIC)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdBy": {
"type": "string",
"description": "Created by identifier"
},
"updatedBy": {
"type": "string",
"description": "Updated by identifier"
}
},
"required": [
"id",
"uuid",
"tenantId",
"createdByUserId",
"name",
"type",
"payloadTemplate",
"options",
"renderMode",
"accessLevel",
"isVersioned",
"versionCounter",
"createdAt",
"updatedAt"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/qr-codes/{uuid}
Get QR code by UUID
Get detailed information about a QR code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
},
"name": {
"type": "string",
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Whether versioning is enabled"
},
"versionCounter": {
"type": "integer",
"description": "Current version number"
},
"latestMediaId": {
"type": "string",
"format": "uuid",
"description": "Latest media file UUID"
},
"publicUrl": {
"type": "string",
"description": "Public URL for embedding (only if accessLevel is PUBLIC)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdBy": {
"type": "string",
"description": "Created by identifier"
},
"updatedBy": {
"type": "string",
"description": "Updated by identifier"
}
},
"required": [
"id",
"uuid",
"tenantId",
"createdByUserId",
"name",
"type",
"payloadTemplate",
"options",
"renderMode",
"accessLevel",
"isVersioned",
"versionCounter",
"createdAt",
"updatedAt"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/qr-codes/{uuid}
Update QR code
Update an existing QR code
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Enable versioning"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
},
"name": {
"type": "string",
"description": "QR code name"
},
"description": {
"type": "string",
"description": "QR code description"
},
"type": {
"type": "string",
"enum": [
"TEXT",
"URL",
"LANDING_PAGE",
"CONTACT",
"LOCATION",
"CUSTOM"
]
},
"payloadTemplate": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
],
"description": "Payload definition"
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"renderMode": {
"type": "string",
"enum": [
"LIVE",
"STATIC"
]
},
"accessLevel": {
"type": "string",
"enum": [
"PUBLIC",
"AUTHENTICATED",
"API_KEY",
"PRIVATE"
],
"description": "Access control: PUBLIC (anyone), AUTHENTICATED (logged in), API_KEY (requires key/token), PRIVATE (tenant only)",
"default": "PUBLIC"
},
"isVersioned": {
"type": "boolean",
"description": "Whether versioning is enabled"
},
"versionCounter": {
"type": "integer",
"description": "Current version number"
},
"latestMediaId": {
"type": "string",
"format": "uuid",
"description": "Latest media file UUID"
},
"publicUrl": {
"type": "string",
"description": "Public URL for embedding (only if accessLevel is PUBLIC)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdBy": {
"type": "string",
"description": "Created by identifier"
},
"updatedBy": {
"type": "string",
"description": "Updated by identifier"
}
},
"required": [
"id",
"uuid",
"tenantId",
"createdByUserId",
"name",
"type",
"payloadTemplate",
"options",
"renderMode",
"accessLevel",
"isVersioned",
"versionCounter",
"createdAt",
"updatedAt"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/qr-codes/{uuid}
Delete QR code
Delete a QR code
📤 RESPONSE 204
QR code deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/qr-codes/{uuid}/download
Download QR code image
Download QR code as PNG or SVG
📤 RESPONSE 200
Inline Schema
Response: QR code image
Schema: QR code image
{
"description": "QR code image",
"type": "string",
"format": "binary"
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/qr-codes/{uuid}/regenerate
Regenerate QR code
Force regeneration of static QR code image
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"force": {
"type": "boolean",
"description": "Force regeneration even if unchanged",
"default": false
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"regenerated": {
"type": "boolean",
"description": "Whether regeneration was performed"
},
"versionNumber": {
"type": "integer",
"description": "New version number if versioned"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "New media file UUID"
},
"checksum": {
"type": "string",
"description": "SHA-256 checksum"
}
},
"required": [
"regenerated"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/qr-codes/{uuid}/versions
Get QR code versions
Get version history for a QR code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"qrCodeId": {
"type": "integer",
"description": "Parent QR code ID"
},
"versionNumber": {
"type": "integer",
"description": "Version number"
},
"mediaFileId": {
"type": "string",
"format": "uuid",
"description": "Media file UUID"
},
"checksum": {
"type": "string",
"description": "SHA-256 checksum of rendered image"
},
"optionsSnapshot": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code foreground",
"default": "#000000"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Hex color for QR code background",
"default": "#FFFFFF"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096,
"description": "Size dimension in pixels or ems",
"default": 256
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
],
"description": "Unit for size dimension",
"default": "px"
},
"errorCorrectionLevel": {
"type": "string",
"enum": [
"L",
"M",
"Q",
"H"
],
"description": "Error correction: L (Low ~7%), M (Medium ~15%), Q (Quartile ~25%), H (High ~30%)"
},
"margin": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Margin in module units",
"default": 4
},
"themeId": {
"type": "string",
"description": "Optional theme identifier"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether icon overlay is enabled"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string",
"description": "Hex color for icon (inherits foreground if not set)"
},
"mediaId": {
"type": "string",
"format": "uuid",
"description": "UUID of media file for icon image"
}
},
"required": [
"enabled",
"size"
]
}
},
"required": [
"foregroundColor",
"backgroundColor",
"size",
"sizeUnit",
"errorCorrectionLevel",
"margin",
"printProfile",
"icon"
]
},
"payloadSnapshot": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Property type (e.g., LOCATION, TEXT, URL)"
},
"property": {
"type": "string",
"description": "Property key (e.g., lat, lng, url)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"description": "Property value"
}
},
"required": [
"type",
"property",
"value"
]
}
}
]
},
"renderDurationMs": {
"type": "integer",
"description": "Render duration in milliseconds"
},
"fileSizeBytes": {
"type": "integer",
"description": "File size in bytes"
},
"imageFormat": {
"type": "string",
"enum": [
"png",
"svg"
],
"description": "Image format"
},
"renderedAt": {
"type": "string",
"format": "date-time",
"description": "Render timestamp"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
}
},
"required": [
"id",
"uuid",
"qrCodeId",
"versionNumber",
"checksum",
"optionsSnapshot",
"payloadSnapshot",
"renderedAt",
"createdAt"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/qr-codes/{uuid}/links
Get QR code links
Get entities linked to a QR code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"qrCodeId": {
"type": "integer",
"description": "QR code ID"
},
"linkedType": {
"type": "string",
"enum": [
"space",
"resource",
"contact",
"user",
"calendar_entry"
],
"description": "Linked entity type"
},
"linkedId": {
"type": "integer",
"description": "Linked entity ID"
},
"linkedUuid": {
"type": "string",
"format": "uuid",
"description": "Linked entity UUID"
},
"permissionSource": {
"type": "string",
"description": "Permission source description"
},
"inheritsPermissions": {
"type": "boolean",
"description": "Whether permissions are inherited"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
}
},
"required": [
"id",
"uuid",
"qrCodeId",
"linkedType",
"inheritsPermissions",
"createdAt",
"updatedAt"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/qr-codes/{uuid}/links
Link QR code to entity
Create a link between QR code and another entity
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"linkedType": {
"type": "string",
"enum": [
"space",
"resource",
"contact",
"user",
"calendar_entry"
],
"description": "Entity type to link"
},
"linkedId": {
"type": "integer",
"description": "Entity ID to link"
},
"linkedUuid": {
"type": "string",
"format": "uuid",
"description": "Entity UUID to link"
},
"permissionSource": {
"type": "string",
"description": "Permission source description"
},
"inheritsPermissions": {
"type": "boolean",
"description": "Inherit permissions from linked entity",
"default": true
}
},
"required": [
"linkedType"
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Database ID"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "UUID identifier"
},
"qrCodeId": {
"type": "integer",
"description": "QR code ID"
},
"linkedType": {
"type": "string",
"enum": [
"space",
"resource",
"contact",
"user",
"calendar_entry"
],
"description": "Linked entity type"
},
"linkedId": {
"type": "integer",
"description": "Linked entity ID"
},
"linkedUuid": {
"type": "string",
"format": "uuid",
"description": "Linked entity UUID"
},
"permissionSource": {
"type": "string",
"description": "Permission source description"
},
"inheritsPermissions": {
"type": "boolean",
"description": "Whether permissions are inherited"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp"
},
"createdByUserId": {
"type": "string",
"format": "uuid",
"description": "Creator user UUID"
}
},
"required": [
"id",
"uuid",
"qrCodeId",
"linkedType",
"inheritsPermissions",
"createdAt",
"updatedAt"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/qr-codes/{uuid}/links/{linkId}
Unlink QR code from entity
Delete a link between QR code and entity
📤 RESPONSE 204
Link deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Realtime
POST
/api/v1/services/realtime/channels
No summary
Create a realtime channel (broadcast, peer, group)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"channel_type": {
"type": "string",
"enum": [
"broadcast",
"peer",
"group"
]
},
"entity_type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"metadata": {
"type": "object",
"additionalProperties": true,
"nullable": true
}
},
"required": [
"channel_type",
"entity_type"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"channel_name": {
"type": "string"
},
"channel_type": {
"type": "string",
"enum": [
"broadcast",
"peer",
"group"
]
},
"entity_type": {
"type": "string"
},
"entity_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deleted_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"channel_name",
"channel_type",
"entity_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/realtime/channels
No summary
List realtime channels for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"channel_name": {
"type": "string"
},
"channel_type": {
"type": "string",
"enum": [
"broadcast",
"peer",
"group"
]
},
"entity_type": {
"type": "string"
},
"entity_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deleted_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"channel_name",
"channel_type",
"entity_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/services/realtime/channels/{id}
No summary
Get a realtime channel by id
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"channel_name": {
"type": "string"
},
"channel_type": {
"type": "string",
"enum": [
"broadcast",
"peer",
"group"
]
},
"entity_type": {
"type": "string"
},
"entity_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deleted_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"channel_name",
"channel_type",
"entity_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/services/realtime/channels/{id}
No summary
Soft delete a realtime channel
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"channel_name": {
"type": "string"
},
"channel_type": {
"type": "string",
"enum": [
"broadcast",
"peer",
"group"
]
},
"entity_type": {
"type": "string"
},
"entity_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deleted_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"channel_name",
"channel_type",
"entity_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Realtime Events
GET
/api/v1/services/realtime/events/missed
No summary
Get missed events (for catch-up on reconnect). Pattern supports wildcards: "user:*", "*:deleted", "*"
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"data": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
]
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Registration
POST
/api/v1/public/auth/register-user
Register new user
Self-service user registration with email verification
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"displayName": {
"type": "string",
"maxLength": 255
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"userId": {
"type": "string",
"format": "uuid"
},
"requiresVerification": {
"type": "boolean"
}
},
"required": [
"message",
"userId",
"requiresVerification"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/resend-verification
Resend verification email
Resend email verification to a registered but unverified user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Resource Move Requests
POST
/api/v1/secure/resources/{id}/move
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"targetSpaceId"
],
"properties": {
"targetSpaceId": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/resource-requests
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/resource-requests/{id}/approve
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/resource-requests/{id}/reject
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"rejectionReason"
],
"properties": {
"rejectionReason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/resource-requests/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"reason": {
"type": [
"null",
"string"
]
},
"rejection_reason": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"completed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Resource Owners
GET
/api/v1/secure/resources/{id}/owners
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
]
},
"created_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"user_id"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/owners
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"userIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "null"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/owners/{userId}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "null"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Resources
GET
/api/v1/secure/resources/
No summary
List all resources in tenant with filtering and pagination
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the current space (resolved)"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
"description": "ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"category_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tag_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translations_i18n": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
}
},
{
"type": "null"
}
],
"description": "Translations for additional languages (excludes base language)"
}
},
"required": [
"name",
"status"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the current space (resolved)"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the current space (resolved)"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/resources/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
"description": "ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"category_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tag_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translations_i18n": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
}
},
{
"type": "null"
}
],
"description": "Translations for additional languages (excludes base language)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the current space (resolved)"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/detach
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Display name of the current space (resolved)"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/tags
No summary
Get all tags linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/tags
No summary
Link a tag to a resource (creates tag if it doesn't exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name (will be normalized)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/tags/{tagId}
No summary
Unlink a tag from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/categories
No summary
Get all categories linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/categories
No summary
Link a category to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"category_id"
],
"properties": {
"category_id": {
"type": "string",
"format": "uuid",
"description": "Category UUID"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/categories/{categoryId}
No summary
Unlink a category from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/export
No summary
Export resources to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/resources/import
No summary
Import resources from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/resources/{id}/contacts
No summary
Get contacts linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/contacts
No summary
Link a contact to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/contacts/{contactId}
No summary
Unlink a contact from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
S3
GET
/api/v1/secure/storage/s3/
No summary
List all S3 storage configurations for the current tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/
No summary
Create a new S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"region",
"bucket_name",
"access_key_id",
"secret_access_key"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"region": {
"type": "string",
"minLength": 1
},
"bucket_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpoint_url": {
"type": "string",
"maxLength": 500
},
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"fallback_region": {
"type": "string"
},
"fallback_bucket": {
"type": "string"
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": "string"
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": "string"
},
"cdn_domain": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/regions
No summary
Get available AWS S3 regions
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/encryption-types
No summary
Get available S3 encryption types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/cost-estimate
No summary
Estimate monthly S3 costs based on usage parameters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"storageCost": {
"type": "number"
},
"requestsCost": {
"type": "number"
},
"transferCost": {
"type": "number"
},
"totalMonthlyCost": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}
No summary
Get a specific S3 storage configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/s3/{id}
No summary
Update an S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string",
"maxLength": 255
},
"endpoint_url": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"fallback_region": {
"type": [
"string",
"null"
]
},
"fallback_bucket": {
"type": [
"string",
"null"
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": [
"string",
"null"
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": [
"string",
"null"
]
},
"cdn_domain": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/s3/{id}
No summary
Delete an S3 storage configuration
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/{id}/test
No summary
Test S3 connection for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"latencyMs": {
"type": "number"
},
"latency_ms": {
"type": "integer"
},
"bucket_accessible": {
"type": "boolean"
},
"permissions": {
"type": "object",
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"list": {
"type": "boolean"
}
},
"additionalProperties": false
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
No summary
Rotate S3 credentials for a configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"access_key_id",
"secret_access_key"
],
"properties": {
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"rotation_type": {
"type": "string",
"enum": [
"scheduled",
"manual",
"emergency"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}/rotation-history
No summary
Get credential rotation history for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}/metrics
No summary
Get usage metrics for an S3 configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"metric_date": {
"type": "string"
},
"total_storage_bytes": {
"type": "integer"
},
"object_count": {
"type": "integer"
},
"get_requests": {
"type": "integer"
},
"put_requests": {
"type": "integer"
},
"delete_requests": {
"type": "integer"
},
"list_requests": {
"type": "integer"
},
"data_transfer_in_bytes": {
"type": "integer"
},
"data_transfer_out_bytes": {
"type": "integer"
},
"storage_cost_cents": {
"type": "integer"
},
"request_cost_cents": {
"type": "integer"
},
"transfer_cost_cents": {
"type": "integer"
},
"total_cost_cents": {
"type": "integer"
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Search
GET
/api/v1/secure/search/
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Security
GET
/api/v1/secure/security/config
Get tenant security configuration
Returns CORS, CSRF, CSP, and HSTS configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/security/config
Update tenant security configuration
Updates CORS, CSRF, CSP, and HSTS settings
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"cors_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_allowed_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_allowed_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_credentials": {
"type": "boolean"
},
"csrf_enabled": {
"type": "boolean"
},
"csp_policy": {
"type": "object",
"additionalProperties": true,
"description": "Content Security Policy directives"
},
"hsts_enabled": {
"type": "boolean"
},
"hsts_max_age": {
"type": "number"
},
"hsts_include_subdomains": {
"type": "boolean"
},
"hsts_preload": {
"type": "boolean"
},
"x_frame_options": {
"type": "string",
"enum": [
"DENY",
"SAMEORIGIN"
]
},
"x_content_type_options": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/security/csrf-token
Generate CSRF token
Generates a new CSRF token for the authenticated tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"token": {
"type": "string"
},
"expires_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/config
Get global security configuration
Returns platform-wide security settings (DOS, rate limiting, cache, circuit breaker). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/config
Update global security configuration
Update platform-wide security settings. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"dos_time_window_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"dos_block_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 86400
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number",
"minimum": 100,
"maximum": 50000
},
"queue_timeout_ms": {
"type": "number",
"minimum": 1000,
"maximum": 120000
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number",
"minimum": 3,
"maximum": 100
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number",
"minimum": 300,
"maximum": 604800
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number",
"minimum": 50,
"maximum": 99
},
"circuit_breaker_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"circuit_breaker_check_interval_seconds": {
"type": "number",
"minimum": 5,
"maximum": 60
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"cache_default_ttl_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist
List IP blacklist entries
Returns all blocked IP addresses. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/security/ip-blacklist
Block an IP address
Add an IP address to the blacklist. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ip_address"
],
"properties": {
"ip_address": {
"type": "string",
"description": "IPv4 or IPv6 address"
},
"reason": {
"type": "string",
"maxLength": 255,
"description": "Reason for blocking"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Expiration time (null = permanent)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist/{id}
Get IP blacklist entry
Get details of a specific blocked IP. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/ip-blacklist/{id}
Update IP blacklist entry
Update reason or expiration of a blocked IP. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 255
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/security/ip-blacklist/{id}
Unblock an IP address
Remove an IP address from the blacklist. System admin only.
📤 RESPONSE 204
No content
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/events
List security events
Returns security audit log entries. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"ip_address": {
"type": "string",
"nullable": true
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/metrics
Get security metrics
Returns aggregated security metrics (blocked IPs, events, etc.). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_blocked_ips": {
"type": "number"
},
"active_blocked_ips": {
"type": "number"
},
"permanent_blocks": {
"type": "number"
},
"temporary_blocks": {
"type": "number"
},
"auto_blocked_count": {
"type": "number"
},
"events_last_24h": {
"type": "number"
},
"events_by_type": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"events_by_severity": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/logs/security-audit
Get security audit log
System admin only. Get security-related events (failed logins, permission denials, etc.).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"eventType": {
"type": "string",
"enum": [
"login_failed",
"permission_denied",
"api_key_used",
"admin_action"
]
},
"userId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Settings
GET
/api/v1/secure/settings/
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Space Members
GET
/api/v1/secure/spaces/{id}/members
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"space_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"space_id",
"user_id",
"role",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/members
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
}
},
"required": [
"userId",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"space_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"space_id",
"user_id",
"role",
"created_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/members/{userId}
No summary
📤 RESPONSE 204
Member successfully removed
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Spaces
GET
/api/v1/secure/spaces/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of the space home location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
"description": "ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"category_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tag_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translations_i18n": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
}
},
{
"type": "null"
}
],
"description": "Translations for additional languages (excludes base language)"
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of the space home location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of the space home location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/spaces/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$",
"description": "ISO 639-1 language code for base name/description (e.g., en, de, fr, it)"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"category_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tag_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translations_i18n": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
}
},
{
"type": "null"
}
],
"description": "Translations for additional languages (excludes base language)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code for base name/description"
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for additional languages (excludes base language)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"homeLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of the space home location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}
No summary
📤 RESPONSE 204
Space successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/tags
No summary
Get all tags linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/tags
No summary
Link a tag to a space (creates tag if it doesn't exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name (will be normalized)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/tags/{tagId}
No summary
Unlink a tag from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/categories
No summary
Get all categories linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/categories
No summary
Link a category to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"category_id"
],
"properties": {
"category_id": {
"type": "string",
"format": "uuid",
"description": "Category UUID"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/categories/{categoryId}
No summary
Unlink a category from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/export
No summary
Export spaces to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/spaces/import
No summary
Import spaces from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/spaces/{id}/contacts
No summary
Get contacts linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/contacts
No summary
Link a contact to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/contacts/{contactId}
No summary
Unlink a contact from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Stats
GET
/api/v1/secure/stats/counts
Get entity counts
Get counts for multiple entity types in a single call. Optimized for dashboard views.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"spaces": {
"type": "number",
"description": "Total number of spaces"
},
"resources": {
"type": "number",
"description": "Total number of resources"
},
"tags": {
"type": "number",
"description": "Total number of tags"
},
"categories": {
"type": "number",
"description": "Total number of categories"
},
"users": {
"type": "number",
"description": "Total number of users"
},
"groups": {
"type": "number",
"description": "Total number of groups"
},
"contacts": {
"type": "number",
"description": "Total number of contacts"
},
"mediaFiles": {
"type": "number",
"description": "Total number of media files"
}
},
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Storage
GET
/api/v1/secure/storage/system/status
No summary
Get tenant system storage status (quota, usage, available)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
},
"required": [
"tenant_id",
"enabled",
"quota_bytes",
"usage_bytes",
"available_bytes",
"usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/system/stats
No summary
Get system-wide storage statistics (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_tenants": {
"type": "number"
},
"enabled_tenants": {
"type": "number"
},
"total_quota_bytes": {
"type": "number"
},
"total_usage_bytes": {
"type": "number"
},
"average_usage_percent": {
"type": "number"
}
},
"required": [
"total_tenants",
"enabled_tenants",
"total_quota_bytes",
"total_usage_bytes",
"average_usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/
No summary
List all S3 storage configurations for the current tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/
No summary
Create a new S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"region",
"bucket_name",
"access_key_id",
"secret_access_key"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"region": {
"type": "string",
"minLength": 1
},
"bucket_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpoint_url": {
"type": "string",
"maxLength": 500
},
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"fallback_region": {
"type": "string"
},
"fallback_bucket": {
"type": "string"
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": "string"
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": "string"
},
"cdn_domain": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/regions
No summary
Get available AWS S3 regions
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/encryption-types
No summary
Get available S3 encryption types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/cost-estimate
No summary
Estimate monthly S3 costs based on usage parameters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"storageCost": {
"type": "number"
},
"requestsCost": {
"type": "number"
},
"transferCost": {
"type": "number"
},
"totalMonthlyCost": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}
No summary
Get a specific S3 storage configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/s3/{id}
No summary
Update an S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string",
"maxLength": 255
},
"endpoint_url": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"fallback_region": {
"type": [
"string",
"null"
]
},
"fallback_bucket": {
"type": [
"string",
"null"
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": [
"string",
"null"
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": [
"string",
"null"
]
},
"cdn_domain": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/s3/{id}
No summary
Delete an S3 storage configuration
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/{id}/test
No summary
Test S3 connection for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"latencyMs": {
"type": "number"
},
"latency_ms": {
"type": "integer"
},
"bucket_accessible": {
"type": "boolean"
},
"permissions": {
"type": "object",
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"list": {
"type": "boolean"
}
},
"additionalProperties": false
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
No summary
Rotate S3 credentials for a configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"access_key_id",
"secret_access_key"
],
"properties": {
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"rotation_type": {
"type": "string",
"enum": [
"scheduled",
"manual",
"emergency"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}/rotation-history
No summary
Get credential rotation history for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/{id}/metrics
No summary
Get usage metrics for an S3 configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"metric_date": {
"type": "string"
},
"total_storage_bytes": {
"type": "integer"
},
"object_count": {
"type": "integer"
},
"get_requests": {
"type": "integer"
},
"put_requests": {
"type": "integer"
},
"delete_requests": {
"type": "integer"
},
"list_requests": {
"type": "integer"
},
"data_transfer_in_bytes": {
"type": "integer"
},
"data_transfer_out_bytes": {
"type": "integer"
},
"storage_cost_cents": {
"type": "integer"
},
"request_cost_cents": {
"type": "integer"
},
"transfer_cost_cents": {
"type": "integer"
},
"total_cost_cents": {
"type": "integer"
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/
No summary
List storage buckets accessible to current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/buckets/
No summary
Create new storage bucket
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"bucket_name",
"purpose"
],
"properties": {
"bucket_name": {
"type": "string",
"minLength": 3,
"maxLength": 63,
"pattern": "^[a-z0-9-]+$"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"max_file_size_bytes": {
"type": "number",
"minimum": 1024,
"maximum": 10737418240
},
"quota_bytes": {
"type": [
"number",
"null"
],
"minimum": 1024
},
"region": {
"type": "string",
"maxLength": 100
},
"cdn_domain": {
"type": "string",
"maxLength": 255
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000,
"default": 100
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
},
"public": {
"type": "boolean",
"default": false
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/providers
No summary
Get list of storage providers for selection dropdowns
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/providers/stats
No summary
Get storage provider statistics with health and usage data
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"supabase",
"tenant"
]
},
"enabled": {
"type": "boolean"
},
"health": {
"type": "string",
"enum": [
"online",
"degraded",
"offline"
]
},
"usage": {
"type": "object",
"properties": {
"used": {
"type": "number"
},
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"percentage": {
"type": "number"
}
},
"required": [
"used",
"percentage"
],
"additionalProperties": false
},
"priority": {
"type": "number"
},
"isFallback": {
"type": "boolean"
},
"isSystem": {
"type": "boolean"
},
"fileCount": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"type",
"enabled",
"health",
"usage",
"priority",
"isFallback",
"isSystem",
"fileCount"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{id}
No summary
Get storage bucket details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/buckets/{id}
No summary
Update storage bucket
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number",
"minimum": 1024
},
"quota_bytes": {
"type": [
"number",
"null"
],
"minimum": 1024
},
"region": {
"type": "string"
},
"cdn_domain": {
"type": "string"
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/buckets/{id}
No summary
Delete storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/policies
No summary
List RLS policies for storage.objects (read-only, informational)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaname": {
"type": "string"
},
"tablename": {
"type": "string"
},
"policyname": {
"type": "string"
},
"permissive": {
"type": "string"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"cmd": {
"type": "string"
},
"qual": {
"type": "string"
},
"with_check": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/files
No summary
List files in a storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "File or folder name"
},
"id": {
"type": [
"null",
"string"
],
"description": "File ID (null for folders)"
},
"path": {
"type": "string",
"description": "Full path to the file/folder"
},
"isFolder": {
"type": "boolean",
"description": "True if this is a folder"
},
"size": {
"type": "number",
"description": "File size in bytes (0 for folders)"
},
"mimeType": {
"type": [
"null",
"string"
],
"description": "MIME type of the file"
},
"isImage": {
"type": "boolean",
"description": "True if this is an image file"
},
"thumbnailUrl": {
"type": [
"null",
"string"
],
"description": "URL for thumbnail (images only)"
},
"publicUrl": {
"type": [
"null",
"string"
],
"description": "URL for public access/download"
},
"owner": {
"type": [
"null",
"string"
],
"description": "Owner user ID"
},
"createdBy": {
"type": [
"null",
"string"
],
"description": "Created by user ID"
},
"lastAccessedAt": {
"type": [
"null",
"string"
],
"description": "Last access timestamp"
},
"created_at": {
"type": "string",
"description": "Creation timestamp"
},
"updated_at": {
"type": "string",
"description": "Last update timestamp"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "File metadata from storage"
}
},
"required": [
"name",
"path",
"isFolder",
"size",
"isImage",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/buckets/{bucket_name}/files
No summary
Upload file to storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"id": {
"type": "string"
},
"fullPath": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/thumbnail/{*}
No summary
Get thumbnail for an image file
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/download/{*}
No summary
Download file from storage bucket
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/buckets/{bucket_name}/files/{*}
No summary
Delete file from storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/test-upload
No summary
Test client upload to demonstrate RLS blocking (educational purpose)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"bucket_name": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/distribution-config
No summary
Get bucket distribution configuration with configured bucket names
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"strategy": {
"type": "string"
},
"enableDistribution": {
"type": "boolean"
},
"buckets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"purpose": {
"type": "string"
},
"allowedMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"priority": {
"type": "number"
},
"active": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"thumbnailBucket": {
"type": [
"null",
"string"
]
},
"imageBucket": {
"type": [
"null",
"string"
]
},
"videoBucket": {
"type": [
"null",
"string"
]
},
"documentBucket": {
"type": [
"null",
"string"
]
},
"fallbackChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/distribution-config
No summary
Update bucket distribution configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"enum": [
"sequential",
"distributed"
]
},
"fallbackChain": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"thumbnailBucketId": {
"type": "string",
"format": "uuid"
},
"imageBucketId": {
"type": "string",
"format": "uuid"
},
"videoBucketId": {
"type": "string",
"format": "uuid"
},
"documentBucketId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
System
GET
/api/v1/system/health
No summary
Multi-level health check (level=basic|ready|full)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"healthy"
],
"description": "Overall system health status"
},
"version": {
"type": "string",
"description": "API version (e.g., 1.1.123)"
},
"timestamp": {
"type": "string",
"description": "Health check timestamp (ISO 8601)"
},
"degradedServices": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of degraded service names (level=basic)"
},
"ready": {
"type": "boolean",
"description": "System ready status (level=ready, level=full)"
},
"environment": {
"type": "string",
"description": "Deployment environment (level=ready, level=full)"
},
"services": {
"type": "object",
"description": "Detailed health status of all services (level=full)",
"additionalProperties": true
},
"externalApis": {
"type": "object",
"description": "External API connector health summary (level=full)",
"properties": {
"total": {
"type": "integer"
},
"active": {
"type": "integer"
},
"statusBreakdown": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
"supabaseUrl": {
"type": "string",
"description": "Supabase instance URL used by this backend (origin)"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/info
No summary
Complete system information with all service details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded"
],
"description": "Overall system health status"
},
"version": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Full version string (e.g., 1.1.123)"
},
"major": {
"type": "number",
"description": "Major version number"
},
"minor": {
"type": "number",
"description": "Minor version number"
},
"build": {
"type": "number",
"description": "Build number (auto-incremented)"
},
"buildDate": {
"type": "string",
"description": "Build timestamp (ISO 8601)"
}
}
},
"timestamp": {
"type": "string",
"description": "System info check timestamp (ISO 8601)"
},
"environment": {
"type": "string",
"description": "Deployment environment (development, staging, production)"
},
"uptime": {
"type": "number",
"description": "Process uptime in seconds"
},
"services": {
"type": "object",
"description": "Detailed health status of all services",
"additionalProperties": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Service health status (healthy, degraded, unhealthy)"
},
"message": {
"type": "string",
"description": "Human-readable status message"
},
"responseTime": {
"type": "number",
"description": "Service response time in milliseconds"
},
"timestamp": {
"type": "string",
"description": "Last health check timestamp (ISO 8601)"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/dispatcher/run
No summary
Execute scheduled jobs (called by pg_cron)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
},
"jobs_skipped": {
"type": "number"
},
"health_status": {
"type": "object",
"properties": {
"overall": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"services": {
"type": "array",
"items": {
"type": "object",
"properties": {
"service_name": {
"type": "string"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
},
"alerts_sent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/dispatcher/health
No summary
Get service health status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"overall": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"services": {
"type": "array",
"items": {
"type": "object",
"properties": {
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unhealthy"
]
},
"message": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
GET
/api/v1/system/dispatcher/status
No summary
Get dispatcher status and recent runs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"serverless",
"pg-boss"
]
},
"last_run": {
"type": "object",
"nullable": true,
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
},
"health_status": {
"type": "object"
}
}
},
"recent_runs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
}
}
}
},
"recent_alerts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"severity": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"acknowledged": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/dispatcher/alerts/{id}/acknowledge
No summary
Acknowledge a system alert
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"email": {
"type": "string"
},
"isSystemAdmin": {
"type": "boolean"
},
"isTenantAdmin": {
"type": "boolean"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"effectivePermissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"userId",
"tenantId",
"isSystemAdmin",
"isTenantAdmin",
"groups",
"effectivePermissions"
]
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/permissions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/spaces
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"space_id": {
"type": "string"
},
"space_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
}
},
"required": [
"space_id",
"space_name",
"role"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/spaces/manageable
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/resources/manageable
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"space_id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"space_id",
"name"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/can
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"allowed": {
"type": "boolean"
}
},
"required": [
"allowed"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/catalog
No summary
Get catalog of all available features (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"key",
"name",
"description",
"category",
"dependencies",
"defaultEnabled"
],
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tags
GET
/api/v1/secure/taxonomy/tags/
No summary
List tags with optional search
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/{id}
No summary
Get tag by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/tags/{id}
No summary
Delete tag (admin only)
📤 RESPONSE 204
Tag deleted successfully
POST
/api/v1/secure/taxonomy/tags/link
No summary
Link tag to entity (implicit tag creation)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name",
"entity_type",
"entity_id"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/link/bulk
No summary
Link multiple tags to entity at once
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_names",
"entity_type",
"entity_id"
],
"properties": {
"tag_names": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"minItems": 1,
"maxItems": 50
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/tags/{id}/unlink
No summary
Unlink tag from entity (auto-delete tag if no links remain)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Tag unlinked successfully
GET
/api/v1/secure/taxonomy/tags/entity
No summary
Get all tags for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/cloud
No summary
Get tag cloud (most used tags)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tag_id": {
"type": "string",
"format": "uuid"
},
"tag_name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name"
},
"count": {
"type": "number",
"description": "Usage count"
}
},
"required": [
"tag_id",
"tag_name",
"display_name",
"count"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/{id}/entities
No summary
Get all entities tagged with this tag (reverse lookup filter)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/curated
Create curated tag
Create a persistent curated tag (tenant admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name"
},
"group_id": {
"type": "string",
"format": "uuid",
"description": "Group ID for group-owned tags (optional)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/tags/{id}/translations
Update tag translations
Update translations for a tag (all provided locales at once)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"translations"
],
"properties": {
"translations": {
"type": "array",
"items": {
"type": "object",
"required": [
"locale",
"name"
],
"properties": {
"locale": {
"type": "string",
"minLength": 2,
"maxLength": 5,
"description": "Locale code (e.g., en, de, fr, it)"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Translated tag name"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/tags/{id}/upgrade
Upgrade tag to persistent
Upgrade a tag to persistent/curated status (tenant admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/cleanup
Cleanup unused tags
Delete non-persistent tags with no entity links (tenant admin only)
📤 RESPONSE 200
Inline Schema
Response: Cleanup completed
Schema: Cleanup completed
{
"description": "Cleanup completed",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deleted_count": {
"type": "number",
"description": "Number of tags deleted"
}
}
}
}
}
POST
/api/v1/secure/taxonomy/tags/bulk-update
Bulk update tags
Update multiple tags in one transaction (all or nothing)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"updates"
],
"properties": {
"updates": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Tag ID"
},
"persistent": {
"type": "boolean",
"description": "Set persistent/curated status"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/export
No summary
Export tags to Excel/CSV/TSV
📤 RESPONSE 200
Inline Schema
Response: Binary file download
Schema: Binary file download
{
"description": "Binary file download",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/taxonomy/tags/import
No summary
Import tags from Excel/CSV/TSV file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether import completed without critical errors"
},
"dryRun": {
"type": "boolean",
"description": "Whether this was a validation-only dry run"
},
"entityType": {
"type": "string",
"enum": [
"resources",
"spaces",
"categories",
"tags",
"contacts",
"groups",
"type_definitions",
"message_templates"
],
"description": "Entity type that was imported"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number",
"description": "Number of entities created"
},
"updated": {
"type": "number",
"description": "Number of entities updated"
},
"skipped": {
"type": "number",
"description": "Number of entities skipped (merge strategy)"
},
"duplicates": {
"type": "number",
"description": "Number of duplicate entries detected"
},
"errors": {
"type": "number",
"description": "Number of rows with errors"
}
},
"required": [
"created",
"updated",
"skipped",
"duplicates",
"errors"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Warning messages"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"row": {
"type": "number",
"description": "Row number (1-based, including header)"
},
"column": {
"type": "string",
"description": "Column name where error occurred"
},
"value": {
"type": "string",
"description": "Value that caused the error"
},
"identifier": {
"type": "string",
"description": "Entity identifier (name, key, id)"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"code": {
"type": "string",
"description": "Error code for programmatic handling",
"enum": [
"INVALID_FORMAT",
"REQUIRED_FIELD",
"INVALID_UUID",
"DUPLICATE_ENTRY",
"REFERENCE_NOT_FOUND",
"VALIDATION_ERROR",
"IMPORT_ERROR",
"FILE_ERROR"
]
}
},
"required": [
"identifier",
"message",
"code"
],
"additionalProperties": false
},
"description": "Detailed error information per row"
},
"processedRows": {
"type": "number",
"description": "Total number of rows processed"
},
"totalRows": {
"type": "number",
"description": "Total number of rows in file"
}
},
"required": [
"success",
"dryRun",
"entityType",
"stats",
"warnings",
"errors"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
Tenant Domains
GET
/api/v1/secure/tenant-domains/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this domain belongs to"
},
"domain": {
"type": "string",
"description": "Custom domain (e.g., api.wishtree.online)"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain: api (production API), api_int (integration API), auth (authentication), webapp (web application)"
},
"status": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
],
"description": "Verification status: pending, verifying, verified, failed, expired"
},
"verification_token": {
"type": [
"null",
"string"
],
"description": "Unique token for domain verification (32-char alphanumeric)"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"
},
"verified_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when domain was successfully verified (ISO 8601)"
},
"ssl_status": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
],
"description": "SSL certificate status: none, pending, issued, failed, expiring, expired"
},
"ssl_issued_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate was issued (ISO 8601)"
},
"ssl_expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate expires (ISO 8601)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Additional domain-specific settings (JSONB)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"domain",
"domain_type",
"status",
"verification_method",
"ssl_status",
"settings",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of tenant domain objects"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenant-domains/
No summary
Create a new tenant domain configuration for white-label deployment
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"domain",
"domain_type"
],
"properties": {
"domain": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$",
"description": "Custom domain (valid hostname format, no protocol, no path)"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain: api, api_int, auth, webapp"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method (default: cname)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Additional domain-specific settings (JSONB)"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this domain belongs to"
},
"domain": {
"type": "string",
"description": "Custom domain (e.g., api.wishtree.online)"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain: api (production API), api_int (integration API), auth (authentication), webapp (web application)"
},
"status": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
],
"description": "Verification status: pending, verifying, verified, failed, expired"
},
"verification_token": {
"type": [
"null",
"string"
],
"description": "Unique token for domain verification (32-char alphanumeric)"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"
},
"verified_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when domain was successfully verified (ISO 8601)"
},
"ssl_status": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
],
"description": "SSL certificate status: none, pending, issued, failed, expiring, expired"
},
"ssl_issued_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate was issued (ISO 8601)"
},
"ssl_expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate expires (ISO 8601)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Additional domain-specific settings (JSONB)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"domain",
"domain_type",
"status",
"verification_method",
"ssl_status",
"settings",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenant-domains/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this domain belongs to"
},
"domain": {
"type": "string",
"description": "Custom domain (e.g., api.wishtree.online)"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain: api (production API), api_int (integration API), auth (authentication), webapp (web application)"
},
"status": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
],
"description": "Verification status: pending, verifying, verified, failed, expired"
},
"verification_token": {
"type": [
"null",
"string"
],
"description": "Unique token for domain verification (32-char alphanumeric)"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"
},
"verified_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when domain was successfully verified (ISO 8601)"
},
"ssl_status": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
],
"description": "SSL certificate status: none, pending, issued, failed, expiring, expired"
},
"ssl_issued_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate was issued (ISO 8601)"
},
"ssl_expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate expires (ISO 8601)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Additional domain-specific settings (JSONB)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"domain",
"domain_type",
"status",
"verification_method",
"ssl_status",
"settings",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenant-domains/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$",
"description": "Update domain (valid hostname format)"
},
"status": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
],
"description": "Update verification status"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Update verification method"
},
"ssl_status": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
],
"description": "Update SSL certificate status"
},
"ssl_issued_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Update SSL certificate issued timestamp (ISO 8601)"
},
"ssl_expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Update SSL certificate expiration timestamp (ISO 8601)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Update domain-specific settings (JSONB)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this domain belongs to"
},
"domain": {
"type": "string",
"description": "Custom domain (e.g., api.wishtree.online)"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain: api (production API), api_int (integration API), auth (authentication), webapp (web application)"
},
"status": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
],
"description": "Verification status: pending, verifying, verified, failed, expired"
},
"verification_token": {
"type": [
"null",
"string"
],
"description": "Unique token for domain verification (32-char alphanumeric)"
},
"verification_method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method: cname (CNAME record), txt (TXT record), http (HTTP file)"
},
"verified_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when domain was successfully verified (ISO 8601)"
},
"ssl_status": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
],
"description": "SSL certificate status: none, pending, issued, failed, expiring, expired"
},
"ssl_issued_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate was issued (ISO 8601)"
},
"ssl_expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when SSL certificate expires (ISO 8601)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Additional domain-specific settings (JSONB)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"domain",
"domain_type",
"status",
"verification_method",
"ssl_status",
"settings",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenant-domains/{id}
No summary
📤 RESPONSE 204
Tenant domain deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenant-domains/{id}/verify
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"domainId": {
"type": "string",
"format": "uuid",
"description": "Domain configuration ID"
},
"domain": {
"type": "string",
"description": "Domain being verified"
},
"verified": {
"type": "boolean",
"description": "Whether verification succeeded"
},
"method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method used"
},
"details": {
"type": "object",
"properties": {
"cnameTarget": {
"type": [
"null",
"string"
],
"description": "Actual CNAME target found"
},
"expectedTarget": {
"type": "string",
"description": "Expected CNAME target"
},
"txtRecordFound": {
"type": [
"null",
"boolean"
],
"description": "Whether TXT record was found"
},
"httpFileContent": {
"type": [
"null",
"string"
],
"description": "HTTP verification file content"
}
},
"required": [
"expectedTarget"
]
},
"error": {
"type": [
"null",
"object"
],
"properties": {
"code": {
"type": "string",
"enum": [
"DNS_LOOKUP_FAILED",
"CNAME_MISMATCH",
"TXT_NOT_FOUND",
"HTTP_NOT_FOUND",
"TIMEOUT"
],
"description": "Error code if verification failed"
},
"message": {
"type": "string",
"description": "Human-readable error message"
}
}
},
"verifiedAt": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp when verification completed (ISO 8601)"
}
},
"required": [
"domainId",
"domain",
"verified",
"method",
"details"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenant-domains/{id}/verification-instructions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Domain to configure"
},
"domain_type": {
"type": "string",
"enum": [
"api",
"api_int",
"auth",
"webapp"
],
"description": "Type of domain"
},
"method": {
"type": "string",
"enum": [
"cname",
"txt",
"http"
],
"description": "Verification method"
},
"instructions": {
"type": "object",
"properties": {
"cname": {
"type": "object",
"properties": {
"record_type": {
"type": "string",
"description": "DNS record type (CNAME)"
},
"name": {
"type": "string",
"description": "DNS record name (subdomain)"
},
"value": {
"type": "string",
"description": "DNS record value (target)"
},
"ttl": {
"type": "number",
"description": "Recommended TTL in seconds"
}
}
},
"txt": {
"type": "object",
"properties": {
"record_type": {
"type": "string",
"description": "DNS record type (TXT)"
},
"name": {
"type": "string",
"description": "DNS record name"
},
"value": {
"type": "string",
"description": "Verification token"
}
}
},
"http": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL to create verification file"
},
"content": {
"type": "string",
"description": "File content to place at URL"
}
}
}
}
}
},
"required": [
"domain",
"domain_type",
"method",
"instructions"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenant Metrics
GET
/api/v1/secure/tenants/{id}/metrics/snapshot
Get metrics snapshot
Retrieve real-time snapshot of current tenant metrics
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"tenantName": {
"type": "string",
"description": "Tenant name"
},
"users": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of users"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active users (last 30 days)"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of spaces"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active spaces"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of resources"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active resources"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"usedBytes": {
"type": "integer",
"minimum": 0,
"description": "Storage used in bytes"
},
"usedGB": {
"type": "number",
"minimum": 0,
"description": "Storage used in gigabytes"
}
},
"required": [
"usedBytes",
"usedGB"
],
"additionalProperties": false
},
"snapshotAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of snapshot"
}
},
"required": [
"tenantId",
"tenantName",
"users",
"spaces",
"resources",
"storage",
"snapshotAt"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/daily
Get daily metrics
Retrieve historical daily metrics for a tenant (max 90 days)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Metrics record UUID"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"metricDate": {
"type": "string",
"format": "date",
"description": "Metrics date (ISO 8601)"
},
"users": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of users"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active users (last 30 days)"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of spaces"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active spaces"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of resources"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active resources"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"usedBytes": {
"type": "integer",
"minimum": 0,
"description": "Storage used in bytes"
},
"usedGB": {
"type": "number",
"minimum": 0,
"description": "Storage used in gigabytes"
}
},
"required": [
"usedBytes",
"usedGB"
],
"additionalProperties": false
},
"apiCalls": {
"type": [
"null",
"integer"
],
"minimum": 0,
"description": "API calls count (if tracked)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp"
}
},
"required": [
"id",
"tenantId",
"metricDate",
"users",
"spaces",
"resources",
"storage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "Array of daily metrics (sorted by date desc)"
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/monthly
Get monthly metrics
Retrieve historical monthly metrics for a tenant (max 12 months)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Metrics record UUID"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"year": {
"type": "integer",
"minimum": 2024,
"description": "Year"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Month (1-12)"
},
"users": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total users"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak users in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total spaces"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak spaces in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total resources"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak resources in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"averageBytes": {
"type": "integer",
"minimum": 0,
"description": "Average storage in bytes"
},
"averageGB": {
"type": "number",
"minimum": 0,
"description": "Average storage in GB"
},
"peakBytes": {
"type": "integer",
"minimum": 0,
"description": "Peak storage in bytes"
},
"peakGB": {
"type": "number",
"minimum": 0,
"description": "Peak storage in GB"
}
},
"required": [
"averageBytes",
"averageGB",
"peakBytes",
"peakGB"
],
"additionalProperties": false
},
"totalApiCalls": {
"type": [
"null",
"integer"
],
"minimum": 0,
"description": "Total API calls for the month"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp"
}
},
"required": [
"id",
"tenantId",
"year",
"month",
"users",
"spaces",
"resources",
"storage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "Array of monthly metrics (sorted by year/month desc)"
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/quota-warnings
Get quota warnings
Check quota warnings for a tenant (compares usage against limits)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"resource": {
"type": "string",
"enum": [
"users",
"spaces",
"resources",
"storage"
],
"description": "Resource type"
},
"current": {
"type": "number",
"minimum": 0,
"description": "Current usage"
},
"limit": {
"type": "number",
"minimum": 0,
"description": "Configured limit"
},
"percentage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Usage percentage"
},
"threshold": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Warning threshold"
},
"exceeded": {
"type": "boolean",
"description": "Whether limit is exceeded"
}
},
"required": [
"resource",
"current",
"limit",
"percentage",
"threshold",
"exceeded"
],
"additionalProperties": false
},
"description": "Array of quota warnings (only resources at/above threshold)"
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of check"
}
},
"required": [
"tenantId",
"warnings",
"checkedAt"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenant Rate Limits
GET
/api/v1/secure/tenants/{id}/rate-limits
List rate limit configurations
Get all rate limit configurations for a tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/rate-limits
Create rate limit configuration
Create a new rate limit configuration for a tenant
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number",
"minimum": 1
},
"window_seconds": {
"type": "number",
"minimum": 1
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean",
"default": true
}
},
"required": [
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Get rate limit configuration
Get a single rate limit configuration by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Update rate limit configuration
Update an existing rate limit configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number",
"minimum": 1
},
"window_seconds": {
"type": "number",
"minimum": 1
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Delete rate limit configuration
Delete a rate limit configuration
📤 RESPONSE 204
Inline Schema
Response: Default Response
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenant Settings
GET
/api/v1/secure/tenants/{id}/settings
Get all tenant settings
Retrieve all settings categories for a tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"general": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA timezone (e.g., Europe/Zurich)",
"pattern": "^[A-Za-z_]+/[A-Za-z_]+$"
},
"locale": {
"type": "string",
"description": "Locale code in BCP 47 format",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
"limits": {
"type": "object",
"properties": {
"max_users": {
"type": "number",
"description": "Maximum users (-1 = unlimited)"
},
"max_spaces": {
"type": "number",
"description": "Maximum spaces (-1 = unlimited)"
},
"max_resources": {
"type": "number",
"description": "Maximum resources (-1 = unlimited)"
},
"max_storage_gb": {
"type": "number",
"description": "Maximum storage in GB"
},
"max_api_calls_per_day": {
"type": "number",
"description": "Maximum API calls per day"
}
},
"required": [
"max_users",
"max_spaces",
"max_resources",
"max_storage_gb",
"max_api_calls_per_day"
],
"additionalProperties": false
},
"integrations": {
"type": "object",
"properties": {
"calendar": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Calendar integration (Google, Outlook, iCal)"
},
"billing": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Billing integration (Stripe, PayPal)"
},
"email_sendgrid": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "SendGrid email provider"
},
"email_smtp": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "SMTP email provider"
},
"sms_twilio": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Twilio SMS provider"
},
"sms_mail2sms": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Mail2SMS provider"
}
},
"additionalProperties": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false
},
"description": "Extensible integration configurations (email, SMS, calendar, billing, webhooks)"
},
"notifications": {
"type": "object",
"properties": {
"email_notifications": {
"type": "boolean",
"description": "Enable email notifications"
},
"sms_notifications": {
"type": "boolean",
"description": "Enable SMS notifications"
},
"webhook_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Webhook endpoint for notifications"
}
},
"required": [
"email_notifications",
"sms_notifications"
],
"additionalProperties": false
},
"security": {
"type": "object",
"properties": {
"allowed_oauth_redirect_urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "List of allowed frontend URLs for OAuth redirects (e.g., https://app.tenant.com)"
},
"default_oauth_redirect_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Default redirect URL for OAuth (must be in allowed list)"
},
"allowed_cors_origins": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional CORS origins allowed for this tenant (supports wildcards like *.tenant.com)"
},
"oauth_providers_enabled": {
"type": "array",
"items": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"description": "OAuth providers enabled for this tenant (empty = use system defaults)"
},
"password_auth_enabled": {
"type": "boolean",
"description": "Whether email/password authentication is enabled for this tenant"
},
"mfa_required": {
"type": "boolean",
"description": "Whether MFA is required for all users in this tenant"
},
"require_invitation": {
"type": "boolean",
"description": "Whether users must have an invitation to register. System tenant has this enabled by default."
},
"allow_self_registration": {
"type": "boolean",
"description": "Whether users can self-register without invitation (opposite of require_invitation for convenience)"
}
},
"additionalProperties": false
}
},
"required": [
"general",
"limits",
"integrations",
"notifications",
"security"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/settings/{category}
Get category settings
Retrieve settings for a specific category
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications",
"security"
]
},
"settings": {},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/settings/{category}
Update category settings
Update settings for a specific category (partial merge)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Partial settings update (merges with existing). Category-specific validation in service layer."
}
},
"required": [
"settings"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications",
"security"
]
},
"settings": {},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/settings/{category}/reset
Reset settings to defaults
Reset category settings to default values based on tenant type
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_type": {
"type": "string",
"enum": [
"trial",
"paid",
"enterprise"
],
"description": "Tenant type for default template (default: trial)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications",
"security"
]
},
"settings": {},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/settings/history
Get settings history
Retrieve audit trail of settings changes
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications",
"security"
]
},
"settings_before": {
"anyOf": [
{
"type": "object",
"additionalProperties": true,
"description": "Settings before change (JSONB)"
},
{
"type": "null"
}
],
"description": "Settings before change (null on first create)"
},
"settings_after": {
"type": "object",
"additionalProperties": true,
"description": "Settings after change (JSONB)"
},
"changed_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "User who made the change"
},
"changed_at": {
"type": "string",
"format": "date-time"
},
"change_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ip_address": {
"anyOf": [
{
"type": "string",
"format": "ipv4"
},
{
"type": "string",
"format": "ipv6"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"category",
"settings_after",
"changed_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenants
GET
/api/v1/secure/tenants/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"domain",
"ownerEmail",
"ownerPassword"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"domain": {
"type": "string",
"minLength": 2,
"maxLength": 255,
"pattern": "^[a-z0-9.-]+$"
},
"ownerEmail": {
"type": "string",
"format": "email"
},
"ownerPassword": {
"type": "string",
"minLength": 8,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 1000
},
"type": {
"type": "string",
"enum": [
"trial",
"paid",
"enterprise"
]
},
"contactEmail": {
"type": "string",
"format": "email"
},
"contactPhone": {
"type": "string",
"maxLength": 50
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"defaultLanguage": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "Default language (ISO 639-1, e.g., en, de, fr)"
},
"additionalLanguages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"description": "Additional supported languages"
},
"settings": {
"type": "object"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"domain": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 63
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"additional_languages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"storage_distribution_strategy": {
"type": "string",
"enum": [
"sequential",
"distributed"
],
"description": "File distribution strategy: sequential (fill in order) or distributed (group by space/resource)"
},
"storage_fallback_chain": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Array of storage provider IDs in fallback order"
},
"settings": {
"type": "object"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}
No summary
📤 RESPONSE 204
Tenant successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/info
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant": {
"type": "object",
"additionalProperties": true
},
"admin": {
"type": "object",
"additionalProperties": true
},
"api": {
"type": "object",
"additionalProperties": true
},
"groups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"spaces": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/language-sync-status
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove",
"comprehensive"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Error details"
}
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
]
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove",
"comprehensive"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Error details"
}
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
]
}
}
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/language-sync/history
Get language sync history
Get paginated language sync job history with server-side filtering
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/env
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/json
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/oauth-redirect-uris
Get OAuth redirect URIs
Returns OAuth redirect URIs computed from verified custom domains for this tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"redirect_uris": {
"type": "array",
"items": {
"type": "string",
"format": "uri",
"description": "OAuth redirect URI (HTTPS only, format: https://{domain}/auth/v1/callback)"
},
"description": "OAuth redirect URIs computed from verified custom domains (HTTPS only)"
}
},
"required": [
"redirect_uris"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/developer-config
Get developer configuration information
Returns consolidated developer configuration including tenant info, admin user, API endpoints, configuration counts, and domain information.
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/activate
No summary
Activate tenant (pending → trial, or inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for activation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/upgrade
No summary
Upgrade tenant type (trial → paid → enterprise)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"target_type"
],
"properties": {
"target_type": {
"type": "string",
"enum": [
"paid",
"enterprise"
],
"description": "Target plan type"
},
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for upgrade (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/suspend
No summary
Suspend tenant (active → inactive)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for suspension (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/reactivate
No summary
Reactivate tenant (inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for reactivation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/archive
No summary
Archive tenant (inactive → retired)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for archiving (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/lifecycle/history
No summary
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"from_status": {
"type": "string"
},
"to_status": {
"type": "string"
},
"from_type": {
"type": "string"
},
"to_type": {
"type": "string"
},
"action": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"performed_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"from_status",
"to_status",
"action",
"performed_by",
"created_at"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/storage-config
No summary
Get tenant storage provider configuration (credentials masked)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"credentials_encrypted": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"fallback_enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/storage-config
No summary
Update tenant storage provider configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"credentials_encrypted": {
"type": "object",
"additionalProperties": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"fallback_enabled": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}/storage-config
No summary
Delete tenant storage configuration (revert to default Supabase)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/dashboard
Get tenant dashboard
Get all tenant dashboard data in one call: tenant info, metrics, storage, recent activity, and language sync status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"metrics": {
"type": "object",
"properties": {
"users": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"active": {
"type": "number"
},
"trend": {
"type": "number",
"description": "Percentage change vs last period"
}
},
"required": [
"total",
"active"
]
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"active": {
"type": "number"
},
"trend": {
"type": "number"
}
},
"required": [
"total",
"active"
]
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"trend": {
"type": "number"
}
},
"required": [
"total"
]
},
"apiRequests": {
"type": "object",
"properties": {
"last30d": {
"type": "number"
}
},
"required": [
"last30d"
]
}
},
"required": [
"users",
"spaces",
"resources",
"apiRequests"
]
},
"storage": {
"type": "object",
"properties": {
"used": {
"type": "number",
"description": "Storage used in bytes"
},
"limit": {
"type": "number",
"description": "Storage limit in bytes"
},
"percent": {
"type": "number",
"description": "Usage percentage"
}
},
"required": [
"used",
"limit",
"percent"
]
},
"recentActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
}
}
},
"required": [
"type",
"entity_id",
"entity_type",
"timestamp"
]
},
"description": "Last 10 activities"
},
"languageSync": {
"type": "object",
"properties": {
"activeJobs": {
"type": "number"
},
"lastSync": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"activeJobs"
]
}
},
"required": [
"tenant",
"metrics",
"storage",
"recentActivity",
"languageSync"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/log-retention
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"retention_days": {
"type": "number",
"enum": [
30,
60,
90
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/log-retention
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"retention_days"
],
"properties": {
"retention_days": {
"type": "number",
"enum": [
30,
60,
90
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"retention_days": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Timezones (Public)
GET
/api/v1/public/timezones/
List all IANA timezones with optional filters
Get all IANA timezones with optional search and region filtering.
**Performance:** Data is served from RAM cache (no database queries).
First request builds the cache, subsequent requests are instant.
**Priority Timezones:** Europe/Zurich, Europe/Berlin, Europe/Paris,
Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo,
Asia/Singapore, Australia/Sydney are shown first.
**Sorting:** Priority timezones first, then by region alphabetically,
then by city within each region.
No tenant isolation - same data for all tenants.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"timezones": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "IANA timezone name",
"example": "Europe/Zurich"
},
"offset": {
"type": "string",
"description": "Current UTC offset (varies with DST)",
"example": "GMT+1"
},
"offsetMinutes": {
"type": "integer",
"description": "Offset in minutes for sorting"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
},
"city": {
"type": "string",
"description": "City or location name",
"example": "Zurich"
},
"abbreviation": {
"type": "string",
"description": "Timezone abbreviation",
"example": "CET"
}
},
"required": [
"name",
"offset",
"offsetMinutes",
"region",
"city",
"abbreviation"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of timezones matching filters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"description": "Maximum number of results per page"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of results skipped (pagination offset)"
}
},
"required": [
"timezones",
"total",
"limit",
"offset"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/timezones/regions
Get list of available timezone regions
Get all available timezone regions (e.g., Africa, America, Asia, Europe).
**Performance:** Data is served from RAM cache.
Useful for building region dropdown filters.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of available timezone regions",
"example": [
"Africa",
"America",
"Antarctica",
"Asia",
"Atlantic",
"Australia",
"Europe",
"Indian",
"Pacific"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/timezones/{name}
Get timezone by IANA name
Get single timezone by IANA name.
**Performance:** Data is served from RAM cache.
**Example names:** Europe/Zurich, America/New_York, Asia/Tokyo
Note: Use URL encoding for names with special characters
(e.g., America%2FNew_York).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "IANA timezone name",
"example": "Europe/Zurich"
},
"offset": {
"type": "string",
"description": "Current UTC offset",
"example": "GMT+1"
},
"offsetMinutes": {
"type": "integer",
"description": "Offset in minutes"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
},
"city": {
"type": "string",
"description": "City name",
"example": "Zurich"
},
"abbreviation": {
"type": "string",
"description": "Timezone abbreviation",
"example": "CET"
}
},
"required": [
"name",
"offset",
"offsetMinutes",
"region",
"city",
"abbreviation"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Type Definitions
GET
/api/v1/secure/type-definitions/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/type-definitions/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"label",
"schemaDefinition"
],
"properties": {
"name": {
"type": "string",
"description": "Unique type name (kebab-case recommended)",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 100
},
"label": {
"type": "string",
"description": "Human-readable label",
"minLength": 2,
"maxLength": 255
},
"description": {
"type": "string",
"description": "Optional description of the type",
"maxLength": 1000
},
"category": {
"type": "string",
"description": "Category classification (e.g., vehicle, person, location)",
"maxLength": 100
},
"schemaDefinition": {
"type": "object",
"description": "JSON Schema for validating settings",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/type-definitions/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/type-definitions/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"is_active": {
"type": "boolean"
},
"schemaDefinition": {
"type": "object",
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/type-definitions/{id}
No summary
📤 RESPONSE 204
Inline Schema
Response: Default Response
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/type-definitions/{id}/export
No summary
Export a single type definition as JSON
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description"
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
],
"description": "Entity type this definition applies to"
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName",
"isMandatory",
"displayOrder"
]
},
"description": "Property schemas for this type definition"
}
},
"required": [
"name",
"label",
"appliesTo",
"properties"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/type-definitions/export
No summary
Export all type definitions for the tenant as JSON bundle
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Bundle version (e.g., \"1.0\")"
},
"exportedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"tenantId"
]
},
"typeDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description"
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
],
"description": "Entity type this definition applies to"
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName",
"isMandatory",
"displayOrder"
]
},
"description": "Property schemas for this type definition"
}
},
"required": [
"name",
"label",
"appliesTo",
"properties"
]
}
}
},
"required": [
"version",
"exportedAt",
"source",
"typeDefinitions"
]
}
}
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/type-definitions/import
No summary
Import type definitions from JSON. Supports individual type definitions or bundle format.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"typeDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Type definition name (kebab-case, validated in service)"
},
"label": {
"type": "string",
"description": "Human-readable label"
},
"description": {
"type": [
"string",
"null"
]
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource"
]
},
"properties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"displayName": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"isMandatory": {
"type": "boolean"
},
"defaultValue": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"validationRules": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"displayOrder": {
"type": "integer"
}
},
"required": [
"name",
"type",
"displayName"
]
}
}
},
"required": [
"name",
"label",
"appliesTo"
]
}
},
"options": {
"type": "object",
"properties": {
"mergeStrategy": {
"type": "string",
"enum": [
"skip",
"replace",
"merge"
],
"default": "skip",
"description": "How to handle existing type definitions: skip (keep existing), replace (overwrite), merge (update only empty fields)"
},
"dryRun": {
"type": "boolean",
"default": false,
"description": "If true, validate without saving"
}
}
}
},
"required": [
"typeDefinitions"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"duplicates": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Type definition index in input array"
},
"identifier": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/type-definitions/export/excel
No summary
Export type definitions to Excel/CSV/TSV format (shared system)
📤 RESPONSE 200
Inline Schema
Response: Binary file download (xlsx, csv, or tsv)
Schema: Binary file download (xlsx, csv, or tsv)
{
"description": "Binary file download (xlsx, csv, or tsv)",
"type": "string",
"format": "binary"
}
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/type-definitions/import/excel
No summary
Import type definitions from Excel/CSV/TSV file (shared system)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"dryRun": {
"type": "boolean"
},
"stats": {
"type": "object",
"properties": {
"created": {
"type": "number"
},
"updated": {
"type": "number"
},
"skipped": {
"type": "number"
},
"duplicates": {
"type": "number"
},
"errors": {
"type": "number"
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "number",
"description": "Type definition index in input array"
},
"identifier": {
"type": "string"
},
"message": {
"type": "string"
},
"code": {
"type": "string"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
User Groups
GET
/api/v1/secure/groups/users/{userId}/permissions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of permission codes for the user"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Users
GET
/api/v1/secure/users/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"avatar_source",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"displayName": {
"type": "string"
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"avatar_source",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"avatar_source",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/users/{id}
Update user profile
Update user profile information (first name, last name, display name, locale)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"firstName": {
"type": [
"string",
"null"
]
},
"middleName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"displayName": {
"type": [
"string",
"null"
]
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"avatar_source",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/context
Get user context
Get user with all related data: groups, permissions, and recent activity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local first name (e.g., Thai: สมชาย)"
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local middle name (optional)"
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local last name (e.g., Thai: ใจดี)"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Nickname/alias for public display"
},
"avatar_source": {
"type": "string",
"enum": [
"none",
"uploaded",
"remote"
],
"description": "Avatar source: none (generated), uploaded (media service), remote (OAuth provider)"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Resolved avatar URL from selected source"
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"avatar_source",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"permissions"
]
}
},
"permissions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"resource": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"resource",
"action"
]
},
"description": "Flattened list of all user permissions"
},
"recentActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
},
"required": [
"type",
"entity_id",
"entity_type",
"timestamp"
]
},
"description": "Last 5 activities"
}
},
"required": [
"user",
"groups",
"permissions",
"recentActivity"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/contacts
No summary
Get contacts linked to a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/{id}/contacts
No summary
Link a contact to a user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/users/{id}/contacts/{contactId}
No summary
Unlink a contact from a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Webhooks
POST
/api/v1/webhooks/inbound/sendgrid
No summary
Handle SendGrid webhook events (delivered, bounced, opened, clicked)
📥 REQUEST BODY
Inline Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Event type: delivered, bounce, open, click, etc."
},
"email": {
"type": "string",
"format": "email",
"description": "Recipient email address"
},
"timestamp": {
"type": "number",
"description": "Unix timestamp of the event"
},
"sg_message_id": {
"type": "string",
"description": "SendGrid message ID"
},
"reason": {
"type": "string",
"description": "Reason for bounce/drop (if applicable)"
},
"url": {
"type": "string",
"description": "Clicked URL (for click events)"
}
},
"required": [
"event",
"email",
"timestamp"
],
"additionalProperties": true
},
"minItems": 1
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/webhooks/inbound/twilio
No summary
Handle Twilio status callbacks (SMS, WhatsApp delivery status)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"MessageSid": {
"type": "string",
"description": "Twilio message SID"
},
"MessageStatus": {
"type": "string",
"description": "Message status: queued, sent, delivered, failed, undelivered"
},
"ErrorCode": {
"type": "string",
"description": "Twilio error code (if failed)"
},
"ErrorMessage": {
"type": "string",
"description": "Error message (if failed)"
}
},
"required": [
"MessageSid",
"MessageStatus"
],
"additionalProperties": true
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/subscriptions
No summary
List all webhook subscriptions for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"url",
"events",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"total",
"limit",
"offset"
]
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/webhooks/subscriptions
No summary
Create a new webhook subscription
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"url",
"events"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Event types to subscribe to"
},
"enabled": {
"type": "boolean",
"default": true
},
"secret": {
"type": "string",
"description": "HMAC signing secret (will be generated if not provided)"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Custom headers to include in webhook requests"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"url",
"events",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/event-types
No summary
List available webhook event types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"key",
"value",
"description"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/subscriptions/{id}
No summary
Get a specific webhook subscription
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"url",
"events",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/webhooks/subscriptions/{id}
No summary
Update a webhook subscription
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"enabled": {
"type": "boolean"
},
"secret": {
"type": "string"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"url",
"events",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/webhooks/subscriptions/{id}
No summary
Delete a webhook subscription
📤 RESPONSE 204
Successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/webhooks/subscriptions/{id}/test
No summary
Send a test webhook to verify the subscription endpoint
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"statusCode": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"responseBody": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attempts": {
"type": "number"
},
"deliveryTime": {
"type": "number"
}
},
"required": [
"success",
"attempts",
"deliveryTime"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/subscriptions/{id}/logs
No summary
Get delivery logs for a webhook subscription
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"subscription_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"event": {
"type": "string"
},
"url": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"success",
"failed"
]
},
"status_code": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"response_body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attempts": {
"type": "number"
},
"delivery_time_ms": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"event",
"url",
"status",
"attempts",
"delivery_time_ms",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/subscriptions/{id}/stats
No summary
Get delivery statistics for a webhook subscription (last 30 days)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"success": {
"type": "number"
},
"failed": {
"type": "number"
},
"successRate": {
"type": "number"
},
"avgDeliveryTime": {
"type": "number"
}
},
"required": [
"total",
"success",
"failed",
"successRate",
"avgDeliveryTime"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
currencies
GET
/api/v1/public/currencies/
No summary
List all currencies with optional search and pagination
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of currencies"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/currencies/{code}
No summary
Get single currency by ISO 4217 code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/currencies/country/{country}
No summary
Get currencies used by specific country
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of currencies"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
infotags
GET
/api/v1/public/info-tags/
Get info tags by keys (public)
Fetch system-wide info tag content by keys. Used by component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
]
}
GET
/api/v1/public/info-tags/{key}
Get info tag by key (public)
Fetch a single info tag by key. Used by component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
GET
/api/v1/secure/info-tags/
List info tags
Returns all info tags accessible to the current tenant (own + system-wide).
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/info-tags/
Create info tag
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"key",
"title",
"description"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$",
"minLength": 3,
"maxLength": 200
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
},
"examples": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 20
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
GET
/api/v1/secure/info-tags/{id}
Get info tag by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
PATCH
/api/v1/secure/info-tags/{id}
Update info tag
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
},
"examples": {
"type": "array",
"items": {
"type": "string",
"maxLength": 500
},
"maxItems": 20
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
DELETE
/api/v1/secure/info-tags/{id}
Delete info tag
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- 400 Bad Request - Validation error
→ See StandardErrorResponse
Note: 400 Bad Request - Validation error
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 409
- 409 Conflict - Resource already exists or conflict
→ See StandardErrorResponse
Note: 409 Conflict - Resource already exists or conflict
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
phone-codes
GET
/api/v1/public/phone-codes/
No summary
List all international phone codes
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of phone codes"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone-codes/search
No summary
Search phone codes by IDD code (reverse lookup)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of phone codes"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone-codes/{country}
No summary
Get phone code by country ISO code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
public
GET
/api/v1/public/currencies/
No summary
List all currencies with optional search and pagination
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of currencies"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/currencies/{code}
No summary
Get single currency by ISO 4217 code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/currencies/country/{country}
No summary
Get currencies used by specific country
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code (3 uppercase letters)",
"example": "CHF"
},
"name": {
"type": "string",
"description": "Full currency name in English",
"example": "Swiss franc"
},
"symbol": {
"type": "string",
"nullable": true,
"description": "Currency symbol (UTF-8)",
"example": "CHF"
},
"metadata": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 country codes using this currency",
"example": [
"CH",
"LI"
]
},
"decimal_digits": {
"type": "integer",
"description": "Number of decimal digits",
"example": 2
},
"numeric_code": {
"type": "string",
"description": "ISO 4217 numeric code",
"example": "756"
}
},
"additionalProperties": true,
"description": "Additional metadata (countries, decimal digits, numeric code, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when currency was last updated"
}
},
"required": [
"code",
"name",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of currencies"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone-codes/
No summary
List all international phone codes
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of phone codes"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone-codes/search
No summary
Search phone codes by IDD code (reverse lookup)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of phone codes"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/phone-codes/{country}
No summary
Get phone code by country ISO code
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"idd_root": {
"type": "string",
"pattern": "^\\+[0-9]{1,4}$",
"description": "International Direct Dialing root code",
"example": "+41"
},
"idd_suffixes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "Additional dialing suffixes (if applicable)",
"example": [
"0"
]
},
"full_code": {
"type": "string",
"description": "Complete phone code (idd_root + first suffix)",
"example": "+41"
},
"metadata": {
"type": "object",
"properties": {
"country_name": {
"type": "string",
"description": "Country name for display",
"example": "Switzerland"
},
"region": {
"type": "string",
"description": "Geographic region",
"example": "Europe"
}
},
"additionalProperties": true,
"description": "Additional metadata (country name, region, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when phone code was last updated"
}
},
"required": [
"country_code",
"idd_root",
"full_code",
"metadata",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/public/info-tags/
Get info tags by keys (public)
Fetch system-wide info tag content by keys. Used by component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
}
},
"required": [
"data",
"total",
"limit",
"offset"
]
}
GET
/api/v1/public/info-tags/{key}
Get info tag by key (public)
Fetch a single info tag by key. Used by component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string",
"pattern": "^[a-z0-9_.-]+$"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "string"
}
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"additionalProperties": false
}
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"title",
"description",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
Shared Schemas
StandardErrorResponse
Standard error response format used by all error endpoints (4xx and 5xx status codes). See Error Response Standard documentation for details.
{
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error type/code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"statusCode": {
"type": "number",
"description": "HTTP status code"
},
"requestId": {
"type": "string",
"nullable": true,
"description": "Request tracking ID"
},
"details": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"description": "Additional error context (validation errors, etc.)"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Error timestamp (ISO 8601)"
}
},
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"additionalProperties": false
}