Endpoints by Category
Browse endpoints grouped by category, then expand request and response payloads inline without leaving the page.
2FA
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
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 204
2FA method disabled successfully
📤 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/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/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
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/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
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
Admin
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
Returns recent failures, state alerts, and provider health checks for integration diagnostics.
📤 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/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
Returns paginated integration request log records with optional operation, provider, tenant, and date filters.
📤 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
Returns hourly integration metrics with filtering by tenant, operation, provider, and date range.
📤 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/operations
Integration control-plane operations list
Returns integration operations together with recent request and failure totals.
📤 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
Returns a single integration operation with recent metrics and request log history.
📤 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
Returns the aggregated health, success-rate, and state-event overview for the integration control plane.
📤 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/state
Integration state events
Returns integration state transition events and alerts with optional severity and time filters.
📤 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/tenant-overrides
Integration control-plane tenant overrides list
Returns tenant-specific override rules for integration control-plane operations.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Creates or updates a tenant override for operation enablement, provider ordering, quotas, and config.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"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": [
"tenantId",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Removes a tenant-specific integration override entry by its identifier.
📤 RESPONSE 204
Tenant override 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
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
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
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
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/storage/system/stats
Get system storage stats
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
Update tenant system storage
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": {
"tenantId": {
"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
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/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/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/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
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/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
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/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/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
},
"tenantId": {
"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/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
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/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
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
AI Providers
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"
},
"tenantId": {
"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
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"
},
"tenantId": {
"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
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
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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"
},
"tenantId": {
"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}/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"
},
"tenantId": {
"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
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
AI Translation
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
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/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
API Keys
GET
/api/v1/secure/api-keys/
List API keys
Retrieve all API keys configured for the authenticated tenant.
📤 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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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/
Create API key
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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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, tags, categories, type definitions, 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- `tags`: Access to tag lookup data for search and selection\n- `categories`: Access to category lookup data for search and selection\n- `typeDefinitions`: Access to type definition lookup data for app forms and filters\n- `feedbacks`: Access to ratings, reviews, and aggregate feedback data\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 \"tags\": { \"read\": true },\n \"categories\": { \"read\": true },\n \"typeDefinitions\": { \"read\": true },\n \"feedbacks\": { \"read\": true },\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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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
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
GET
/api/v1/secure/api-keys/{id}
Get API key details
Retrieve configuration and status details for a specific API key.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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, tags, categories, type definitions, 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- `tags`: Access to tag lookup data for search and selection\n- `categories`: Access to category lookup data for search and selection\n- `typeDefinitions`: Access to type definition lookup data for app forms and filters\n- `feedbacks`: Access to ratings, reviews, and aggregate feedback data\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 \"tags\": { \"read\": true },\n \"categories\": { \"read\": true },\n \"typeDefinitions\": { \"read\": true },\n \"feedbacks\": { \"read\": true },\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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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
Application Accounts
GET
/api/v1/secure/app-accounts/
List application accounts
Retrieve all application accounts configured for the authenticated tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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/
Create application account
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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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
GET
/api/v1/secure/app-accounts/{id}
Get application account details
Retrieve a specific application account with its current configuration and status.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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}
Update application account
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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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"
},
"tenantId": {
"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"
}
}
},
"tags": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"categories": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"typeDefinitions": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
},
"feedbacks": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"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",
"tenantId",
"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/{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
Get application account usage statistics
Retrieve usage metrics and activity statistics for a specific application account.
📤 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/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"
},
"tenantId": {
"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
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 204
Request cancelled successfully
📤 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/{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"
},
"tenantId": {
"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
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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"
},
"tenantId": {
"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
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
Audit Logs
GET
/api/v1/secure/audit-logs/
List audit logs
Retrieve paginated audit log entries with optional filtering by actor, action, resource, and time range.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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/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
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": "Legacy alias for tenantId. Accepted for backward compatibility."
}
},
"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/oauth/exchange
Exchange OAuth client callback code
Completes Track 2 OAuth authentication from a client-owned callback route without exposing direct Supabase auth setup to the frontend
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"description": "Authorization code returned to the client-owned callback route"
},
"pveState": {
"type": "string",
"format": "uuid",
"description": "PVE-issued OAuth state ID returned in the client-owned callback route"
}
},
"required": [
"code",
"pveState"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"authenticated",
"registration_required"
]
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"requiresPostAuthFlow": {
"type": "boolean"
},
"user": {
"anyOf": [
{
"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
},
{
"type": "null"
}
]
},
"registration": {
"anyOf": [
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"avatarUrl": {
"type": "string",
"format": "uri"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"email"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"status",
"provider",
"accessToken",
"refreshToken",
"requiresPostAuthFlow"
],
"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/auth/oauth/initiate
Initiate OAuth client callback flow
Starts Track 2 OAuth authentication for client-owned callback routes
📥 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",
"minLength": 1,
"description": "Client-owned callback URI (https://, chrome-extension://, or app:// depending on configuration)"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Optional tenant ID for multi-tenant login"
},
"clientType": {
"type": "string",
"enum": [
"web",
"extension",
"desktop",
"mobile"
],
"description": "Client type initiating the OAuth broker flow"
}
},
"required": [
"provider",
"redirectUrl",
"clientType"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"oauthUrl": {
"type": "string",
"description": "OAuth provider authorization URL"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"clientType": {
"type": "string",
"enum": [
"web",
"extension",
"desktop",
"mobile"
]
},
"redirectMode": {
"type": "string",
"enum": [
"client_callback"
]
},
"stateId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"oauthUrl",
"provider",
"clientType",
"redirectMode",
"stateId",
"expiresAt"
],
"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/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
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"
},
"capabilities": {
"type": "object",
"properties": {
"server_callback": {
"type": "boolean",
"description": "Whether the provider supports the legacy backend callback flow"
},
"client_callback": {
"type": "boolean",
"description": "Whether the provider supports the Track 2 client callback broker flow"
},
"native_mobile": {
"type": "boolean",
"description": "Whether the provider is recommended for native mobile SDK flows"
}
},
"required": [
"server_callback",
"client_callback",
"native_mobile"
],
"additionalProperties": false
}
},
"required": [
"id",
"name",
"enabled",
"capabilities"
],
"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/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/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",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"id",
"email",
"tenantId"
],
"additionalProperties": false
},
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"domain": {
"type": "string"
}
},
"required": [
"id",
"name",
"domain"
],
"additionalProperties": false
},
"message": {
"type": "string"
}
},
"required": [
"user",
"tenant",
"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 409
- 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 in an existing tenant context. Provide tenantId, X-Tenant-ID, or use a mapped tenant domain.
📥 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
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant context for self-registration. Required unless the tenant is resolved from X-Tenant-ID or a mapped custom domain."
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"userId": {
"type": "string",
"format": "uuid"
},
"requiresVerification": {
"type": "boolean"
},
"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"
}
},
"required": [
"id",
"email",
"displayName",
"tenantId"
],
"additionalProperties": false
},
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"domain": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug",
"domain"
],
"additionalProperties": false
}
},
"required": [
"message",
"userId",
"requiresVerification",
"user",
"tenant"
],
"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/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/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/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
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 204
2FA method disabled successfully
📤 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/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/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
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/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
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/account
Delete current account
Retire the current PVE account, suspend tenant access, and soft-delete the backing auth user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"accountClosedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"success",
"message",
"accountClosedAt"
],
"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/auth/client-config/realtime
Get secure realtime client configuration
Returns runtime realtime configuration for authenticated clients without requiring frontend build-time Supabase environment variables
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"supabaseUrl": {
"type": "string",
"format": "uri"
},
"supabaseAnonKey": {
"type": "string"
}
},
"required": [
"supabaseUrl",
"supabaseAnonKey"
],
"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/auth/default-tenant
Set default tenant
Set the default tenant that will be used on login
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant ID to set as default"
}
},
"required": [
"tenantId"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"defaultTenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"success",
"defaultTenantId"
],
"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/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/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
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
POST
/api/v1/secure/auth/logout
Logout current user
Invalidate the current authenticated session and clear the refresh token cookie
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
📤 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/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"
},
"locale": {
"type": "string"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"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",
"locale",
"settings",
"typeDefinitionId",
"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
PATCH
/api/v1/secure/auth/me
Update current user
Update the current authenticated user profile and typed settings payload
📥 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"
]
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition ID or type name to validate the user settings payload"
}
},
"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": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"type": "string"
},
"locale": {
"type": "string"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"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",
"locale",
"settings",
"typeDefinitionId",
"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
POST
/api/v1/secure/auth/me/change-password
Change current user password
Verify the current password and update the current authenticated user password.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"currentPassword",
"newPassword"
],
"properties": {
"currentPassword": {
"type": "string",
"minLength": 8
},
"newPassword": {
"type": "string",
"minLength": 8
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success",
"message"
],
"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/auth/me/preferences
Reset current user settings
Reset the current authenticated user typed settings payload to the system wildcard default
📤 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"
},
"locale": {
"type": "string"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"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",
"locale",
"settings",
"typeDefinitionId",
"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
POST
/api/v1/secure/auth/merge-accounts
Merge secondary auth account
Merges a verified secondary auth account into the current authenticated user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"secondaryAccessToken": {
"type": "string",
"minLength": 1,
"description": "Access token for the secondary account to merge into the current authenticated account"
},
"mergeMode": {
"type": "string",
"enum": [
"move_all",
"safe_only"
],
"description": "Requested merge mode"
},
"dryRun": {
"type": "boolean",
"description": "Whether to calculate the merge plan without applying changes"
}
},
"required": [
"secondaryAccessToken"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"primaryUserId": {
"type": "string",
"format": "uuid"
},
"secondaryUserId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"planned",
"completed",
"failed",
"dry_run"
]
},
"reassignedEntities": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"deletedSecondaryAccount": {
"type": "boolean"
}
},
"required": [
"primaryUserId",
"secondaryUserId",
"status",
"reassignedEntities",
"warnings",
"deletedSecondaryAccount"
],
"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/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
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
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
POST
/api/v1/secure/auth/switch-tenant
Switch tenant
Switch the active tenant for the current session
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Target tenant ID to switch to"
}
},
"required": [
"tenantId"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"type": "string"
},
"tenantSlug": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"success",
"tenantId",
"tenantName",
"tenantSlug",
"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
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/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
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": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"tenantId",
"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
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"
},
"tenantId": {
"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"
},
"tenantName": {
"type": "string"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"user_id",
"tenantId",
"role",
"tenantName",
"tenantSlug"
],
"additionalProperties": false
}
},
"activeTenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"defaultTenantId": {
"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
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
AuthHelper
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
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
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
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
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
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/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
Avatar
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
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
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
Calendar
GET
/api/v1/secure/calendar/
List calendars
Retrieve calendars visible to the current user with optional 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"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedEntity": {
"type": "object",
"properties": {
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"userId",
"resourceId",
"spaceId"
],
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
}
},
"required": [
"id",
"tenantId",
"kind",
"name",
"timezone",
"visibility",
"policy",
"metadata",
"typeDefinitionId",
"linkedEntity",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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
POST
/api/v1/secure/calendar/
Create calendar
Create a calendar and configure its visibility, linkage, and metadata.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"linkedUserId": {
"type": "string",
"format": "uuid"
},
"linkedResourceId": {
"type": "string",
"format": "uuid"
},
"linkedSpaceId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"name",
"timezone"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedEntity": {
"type": "object",
"properties": {
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"userId",
"resourceId",
"spaceId"
],
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
}
},
"required": [
"id",
"tenantId",
"kind",
"name",
"timezone",
"visibility",
"policy",
"metadata",
"typeDefinitionId",
"linkedEntity",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/{id}
Delete calendar
Delete a calendar that the current user is allowed to manage.
📤 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/calendar/{id}
Get calendar by id
Retrieve a calendar with its current configuration and the current visit metric summary fields. The response can include totalVisits and lastVisitedAt when entity visit metrics are enabled, but it does not increment the counter. Client web and mobile apps must call the tracking endpoint explicitly when a real user view should count as a visit.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedEntity": {
"type": "object",
"properties": {
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"userId",
"resourceId",
"spaceId"
],
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
}
},
"required": [
"id",
"tenantId",
"kind",
"name",
"timezone",
"visibility",
"policy",
"metadata",
"typeDefinitionId",
"linkedEntity",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/{id}
Update calendar
Update calendar metadata, visibility, policy, or type definition settings.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedEntity": {
"type": "object",
"properties": {
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"userId",
"resourceId",
"spaceId"
],
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
}
},
"required": [
"id",
"tenantId",
"kind",
"name",
"timezone",
"visibility",
"policy",
"metadata",
"typeDefinitionId",
"linkedEntity",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/{id}/reminders
List reminders for a calendar
Retrieve reminders configured for a calendar and its entries.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"recurrenceMasterId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTriggeredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"calendarEntryId",
"recurrenceMasterId",
"channel",
"offsetMinutes",
"isEnabled",
"nextTriggerAt",
"lastTriggeredAt",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
}
},
"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/calendar/{id}/reminders/dispatch-preview
Preview due reminders for dispatch without worker orchestration
Preview reminders that would be dispatched for a calendar without triggering worker execution.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"asOf": {
"type": "string",
"format": "date-time"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"reminder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"recurrenceMasterId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTriggeredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"calendarEntryId",
"recurrenceMasterId",
"channel",
"offsetMinutes",
"isEnabled",
"nextTriggerAt",
"lastTriggeredAt",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"additionalProperties": false
},
"targetKind": {
"type": "string",
"enum": [
"entry",
"recurrence_instance"
]
},
"targetId": {
"type": "string",
"format": "uuid"
},
"targetStartsAt": {
"type": "string",
"format": "date-time"
},
"targetEndsAt": {
"type": "string",
"format": "date-time"
},
"targetTimezone": {
"type": "string"
},
"deliveryKey": {
"type": "string"
}
},
"required": [
"reminder",
"targetKind",
"targetId",
"targetStartsAt",
"targetEndsAt",
"targetTimezone",
"deliveryKey"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
}
},
"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/calendar/{id}/visit-metrics/reset
Reset calendar visit metrics
Reset stored visit metrics for a calendar and return the updated summary.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityId": {
"type": "string",
"format": "uuid"
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"lastVisitedByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastVisitedByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastResetByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastResetByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetReason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"required": [
"entityId",
"totalVisits",
"lastVisitedAt",
"lastVisitedByActorType",
"lastVisitedByActorId",
"lastResetAt",
"lastResetByActorType",
"lastResetByActorId",
"lastResetReason"
],
"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/calendar/entries
List calendar entries in a bounded window
Retrieve calendar entries within a bounded time window with optional calendar filtering.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"locationName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locationPayload": {
"type": "object",
"additionalProperties": true
},
"approvalState": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
{
"type": "null"
}
]
},
"approvalRequestId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"kind",
"status",
"visibility",
"title",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"ownerUserId",
"metadata",
"typeDefinitionId",
"locationName",
"locationPayload",
"approvalState",
"approvalRequestId",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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
POST
/api/v1/secure/calendar/entries
Create calendar entry
Create an event, booking, reservation, hold, or reminder task in a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"locationName": {
"type": "string",
"maxLength": 255
},
"locationPayload": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"calendarId",
"kind",
"title",
"startsAt",
"endsAt",
"timezone"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"locationName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locationPayload": {
"type": "object",
"additionalProperties": true
},
"approvalState": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
{
"type": "null"
}
]
},
"approvalRequestId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"kind",
"status",
"visibility",
"title",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"ownerUserId",
"metadata",
"typeDefinitionId",
"locationName",
"locationPayload",
"approvalState",
"approvalRequestId",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/entries/{id}
Delete calendar entry
Delete a calendar entry from the calendar timeline.
📤 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/calendar/entries/{id}
Get calendar entry by id
Retrieve a specific calendar entry with its current state and 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"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"locationName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locationPayload": {
"type": "object",
"additionalProperties": true
},
"approvalState": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
{
"type": "null"
}
]
},
"approvalRequestId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"kind",
"status",
"visibility",
"title",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"ownerUserId",
"metadata",
"typeDefinitionId",
"locationName",
"locationPayload",
"approvalState",
"approvalRequestId",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/entries/{id}
Update calendar entry
Update the content, timing, visibility, or metadata of a calendar entry.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"locationName": {
"type": "string",
"maxLength": 255
},
"locationPayload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"locationName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locationPayload": {
"type": "object",
"additionalProperties": true
},
"approvalState": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
{
"type": "null"
}
]
},
"approvalRequestId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"kind",
"status",
"visibility",
"title",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"ownerUserId",
"metadata",
"typeDefinitionId",
"locationName",
"locationPayload",
"approvalState",
"approvalRequestId",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/entries/{id}/respond
Respond to calendar assignment
Record the current user's response to a calendar assignment or participation request.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"responseStatus": {
"type": "string",
"enum": [
"pending",
"accepted",
"declined",
"tentative"
]
}
},
"required": [
"responseStatus"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"type": "string",
"format": "uuid"
},
"actorType": {
"type": "string",
"enum": [
"user",
"group"
]
},
"actorUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorGroupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"enum": [
"attendee",
"assignee",
"owner",
"observer"
]
},
"responseStatus": {
"type": "string",
"enum": [
"pending",
"accepted",
"declined",
"tentative"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarEntryId",
"actorType",
"actorUserId",
"actorGroupId",
"role",
"responseStatus",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/entries/{id}/status
Transition booking status
Change the workflow status of a booking or calendar entry.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
}
},
"required": [
"status"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"event",
"booking",
"reservation",
"hold",
"reminder_task"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"visibility": {
"type": "string",
"enum": [
"default",
"private"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"locationName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locationPayload": {
"type": "object",
"additionalProperties": true
},
"approvalState": {
"anyOf": [
{
"type": "string",
"enum": [
"pending",
"approved",
"rejected",
"cancelled",
"expired"
]
},
{
"type": "null"
}
]
},
"approvalRequestId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"kind",
"status",
"visibility",
"title",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"ownerUserId",
"metadata",
"typeDefinitionId",
"locationName",
"locationPayload",
"approvalState",
"approvalRequestId",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/free-busy
Get free-busy aggregation for visible calendars
Retrieve aggregated busy intervals across visible calendars for the requested time window.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"windowStartsAt": {
"type": "string",
"format": "date-time"
},
"windowEndsAt": {
"type": "string",
"format": "date-time"
},
"slots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"isAllDay": {
"type": "boolean"
}
},
"required": [
"calendarId",
"startsAt",
"endsAt",
"status",
"isAllDay"
],
"additionalProperties": false
}
}
},
"required": [
"windowStartsAt",
"windowEndsAt",
"slots"
],
"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/calendar/recurrence-instances/{id}
Override or cancel a recurrence instance
Override timing, content, or status for a single generated recurrence instance.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"isAllDay": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"instanceState": {
"type": "string",
"enum": [
"generated",
"overridden",
"cancelled"
]
},
"titleOverride": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"descriptionOverride": {
"type": "string"
},
"metadataOverride": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"recurrenceMasterId": {
"type": "string",
"format": "uuid"
},
"sourceEntryId": {
"type": "string",
"format": "uuid"
},
"instanceDate": {
"type": "string",
"format": "date"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"instanceState": {
"type": "string",
"enum": [
"generated",
"overridden",
"cancelled"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"titleOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"descriptionOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadataOverride": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"recurrenceMasterId",
"sourceEntryId",
"instanceDate",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"instanceState",
"status",
"titleOverride",
"descriptionOverride",
"metadataOverride",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/recurrence-masters
Create recurrence master for a calendar entry
Create the recurrence rule and generation window for a recurring calendar entry.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"rootEntryId": {
"type": "string",
"format": "uuid"
},
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
]
},
"intervalCount": {
"type": "integer",
"minimum": 1
},
"byWeekday": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 6
}
},
"byMonthDay": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 31
}
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"untilAt": {
"type": "string",
"format": "date-time"
},
"occurrenceCountLimit": {
"type": "integer",
"minimum": 1
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"generatedWindowDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"metadata": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"calendarId",
"rootEntryId",
"frequency",
"startsAt",
"timezone"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"rootEntryId": {
"type": "string",
"format": "uuid"
},
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
]
},
"intervalCount": {
"type": "integer",
"minimum": 1
},
"byWeekday": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 6
}
},
{
"type": "null"
}
]
},
"byMonthDay": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 31
}
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"untilAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"occurrenceCountLimit": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"generatedWindowDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"rootEntryId",
"frequency",
"intervalCount",
"byWeekday",
"byMonthDay",
"startsAt",
"untilAt",
"occurrenceCountLimit",
"timezone",
"generatedWindowDays",
"metadata",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/recurrence-masters/{id}
Get recurrence master by id
Retrieve the recurrence rule and metadata for a specific recurrence master.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"rootEntryId": {
"type": "string",
"format": "uuid"
},
"frequency": {
"type": "string",
"enum": [
"daily",
"weekly",
"monthly",
"yearly"
]
},
"intervalCount": {
"type": "integer",
"minimum": 1
},
"byWeekday": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 6
}
},
{
"type": "null"
}
]
},
"byMonthDay": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 31
}
},
{
"type": "null"
}
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"untilAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"occurrenceCountLimit": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"generatedWindowDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"rootEntryId",
"frequency",
"intervalCount",
"byWeekday",
"byMonthDay",
"startsAt",
"untilAt",
"occurrenceCountLimit",
"timezone",
"generatedWindowDays",
"metadata",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/recurrence-masters/{id}/instances
List recurrence instances in a bounded window
Retrieve generated and overridden recurrence instances for a recurrence master in a bounded window.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"recurrenceMasterId": {
"type": "string",
"format": "uuid"
},
"sourceEntryId": {
"type": "string",
"format": "uuid"
},
"instanceDate": {
"type": "string",
"format": "date"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"localStartDate": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"localEndDateExclusive": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"isAllDay": {
"type": "boolean"
},
"instanceState": {
"type": "string",
"enum": [
"generated",
"overridden",
"cancelled"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
"titleOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"descriptionOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadataOverride": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"recurrenceMasterId",
"sourceEntryId",
"instanceDate",
"startsAt",
"endsAt",
"localStartDate",
"localEndDateExclusive",
"timezone",
"isAllDay",
"instanceState",
"status",
"titleOverride",
"descriptionOverride",
"metadataOverride",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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
POST
/api/v1/secure/calendar/reminders
Create reminder for an entry or recurrence series
Create a reminder for a calendar entry or recurrence series with a chosen delivery channel.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"type": "string",
"format": "uuid"
},
"recurrenceMasterId": {
"type": "string",
"format": "uuid"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
}
},
"required": [
"calendarId",
"channel",
"offsetMinutes"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"recurrenceMasterId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTriggeredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"calendarEntryId",
"recurrenceMasterId",
"channel",
"offsetMinutes",
"isEnabled",
"nextTriggerAt",
"lastTriggeredAt",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/reminders/{id}
Delete calendar reminder
Delete a reminder from the calendar reminder schedule.
📤 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/calendar/reminders/{id}/ack
Acknowledge reminder dispatch and advance the next trigger
Acknowledge a reminder dispatch event and advance the reminder to its next trigger time.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"triggeredAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"recurrenceMasterId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTriggeredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"calendarEntryId",
"recurrenceMasterId",
"channel",
"offsetMinutes",
"isEnabled",
"nextTriggerAt",
"lastTriggeredAt",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"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/calendar/window
List visible calendar events in a bounded window
Retrieve visible calendar events within a bounded time window for the selected calendars.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"start": {
"type": "string",
"format": "date-time"
},
"end": {
"type": "string",
"format": "date-time"
},
"location": {
"type": "string"
}
},
"required": [
"id",
"title",
"start",
"end"
],
"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
Calendar Admin
GET
/api/v1/secure/admin/calendars/
List tenant admin calendars
Retrieve calendars in the tenant from an administrative perspective 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"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"timezone": {
"type": "string"
},
"activeState": {
"type": "string",
"enum": [
"active",
"deleted"
]
},
"linkedParent": {
"type": "object",
"properties": {
"linkType": {
"type": "string",
"enum": [
"tenant",
"user",
"resource",
"space"
]
},
"entityId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"entityName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"accessMode": {
"type": "string",
"enum": [
"tenant_shared",
"linked_parent"
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"linkType",
"entityId",
"entityName",
"accessMode",
"note"
],
"additionalProperties": false
},
"policySummary": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"bookingPolicy": {
"type": "object",
"additionalProperties": true
},
"reminderDefaults": {
"type": "object",
"additionalProperties": true
},
"adminNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"editableFields": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
]
}
},
"provenance": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"bookingPolicy": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"reminderDefaults": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"adminNotes": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
],
"additionalProperties": false
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes",
"editableFields",
"provenance"
],
"additionalProperties": false
},
"stats": {
"type": "object",
"properties": {
"explicitShareCount": {
"type": "integer"
},
"enabledReminderCount": {
"type": "integer"
},
"nextReminderTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"explicitShareCount",
"enabledReminderCount",
"nextReminderTriggerAt"
],
"additionalProperties": false
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"kind",
"visibility",
"timezone",
"activeState",
"linkedParent",
"policySummary",
"stats",
"updatedAt"
],
"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/admin/calendars/{calendarId}
Get tenant admin calendar detail
Retrieve administrative calendar detail including policy, shares, operational context, and the current visit metric summary fields. This response does not increment visit counters; client web and mobile apps must trigger visit tracking explicitly when a real end-user view should count.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"calendar": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"user_linked",
"resource_linked",
"space_linked",
"tenant_shared"
]
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"policy": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedEntity": {
"type": "object",
"properties": {
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"userId",
"resourceId",
"spaceId"
],
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
}
},
"required": [
"id",
"tenantId",
"kind",
"name",
"timezone",
"visibility",
"policy",
"metadata",
"typeDefinitionId",
"linkedEntity",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"additionalProperties": false
},
"linkedParent": {
"type": "object",
"properties": {
"linkType": {
"type": "string",
"enum": [
"tenant",
"user",
"resource",
"space"
]
},
"entityId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"entityName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"accessMode": {
"type": "string",
"enum": [
"tenant_shared",
"linked_parent"
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"linkType",
"entityId",
"entityName",
"accessMode",
"note"
],
"additionalProperties": false
},
"policy": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"bookingPolicy": {
"type": "object",
"additionalProperties": true
},
"reminderDefaults": {
"type": "object",
"additionalProperties": true
},
"adminNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"editableFields": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
]
}
},
"provenance": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"bookingPolicy": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"reminderDefaults": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"adminNotes": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
],
"additionalProperties": false
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes",
"editableFields",
"provenance"
],
"additionalProperties": false
},
"statistics": {
"type": "object",
"properties": {
"explicitShareCount": {
"type": "integer"
},
"totalReminderCount": {
"type": "integer"
},
"enabledReminderCount": {
"type": "integer"
},
"nextReminderTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"futureEntryCount": {
"type": "integer"
},
"futureInstanceCount": {
"type": "integer"
}
},
"required": [
"explicitShareCount",
"totalReminderCount",
"enabledReminderCount",
"nextReminderTriggerAt",
"futureEntryCount",
"futureInstanceCount"
],
"additionalProperties": false
}
},
"required": [
"calendar",
"linkedParent",
"policy",
"statistics"
],
"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/admin/calendars/{calendarId}/operations
Get bounded tenant admin calendar operations summary
Retrieve a bounded operational summary for a calendar, including upcoming and recent activity.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"asOf": {
"type": "string",
"format": "date-time"
},
"futureWindowDays": {
"type": "integer"
},
"counters": {
"type": "object",
"properties": {
"futureEntryCount": {
"type": "integer"
},
"futureInstanceCount": {
"type": "integer"
},
"pendingReminderCount": {
"type": "integer"
},
"recentMutationCount": {
"type": "integer"
}
},
"required": [
"futureEntryCount",
"futureInstanceCount",
"pendingReminderCount",
"recentMutationCount"
],
"additionalProperties": false
},
"recentMutations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"entityType": {
"type": "string",
"enum": [
"calendar",
"share",
"reminder",
"entry"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"action": {
"type": "string",
"enum": [
"created",
"updated",
"deleted"
]
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"summary": {
"type": "string"
}
},
"required": [
"entityType",
"entityId",
"action",
"occurredAt",
"summary"
],
"additionalProperties": false
}
},
"dispatchFailures": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"count": {
"type": "integer"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"available",
"count",
"note"
],
"additionalProperties": false
}
},
"required": [
"calendarId",
"asOf",
"futureWindowDays",
"counters",
"recentMutations",
"dispatchFailures"
],
"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/admin/calendars/{calendarId}/policy
Update tenant admin calendar policy
Update policy defaults, booking policy, reminder defaults, and admin notes for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"bookingPolicy": {
"type": "object",
"additionalProperties": true
},
"reminderDefaults": {
"type": "object",
"additionalProperties": true
},
"adminNotes": {
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"private",
"shared",
"public_within_tenant"
]
},
"bookingPolicy": {
"type": "object",
"additionalProperties": true
},
"reminderDefaults": {
"type": "object",
"additionalProperties": true
},
"adminNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"editableFields": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
]
}
},
"provenance": {
"type": "object",
"properties": {
"sharePosture": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"visibilityDefault": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"bookingPolicy": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"reminderDefaults": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
},
"adminNotes": {
"type": "string",
"enum": [
"calendar_override",
"calendar_default",
"linked_parent_inherited"
]
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes"
],
"additionalProperties": false
}
},
"required": [
"sharePosture",
"visibilityDefault",
"bookingPolicy",
"reminderDefaults",
"adminNotes",
"editableFields",
"provenance"
],
"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/admin/calendars/{calendarId}/reminders
Get tenant admin reminder health summary
Retrieve reminder health, counts, and configuration state for a calendar from the tenant admin surface.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"summary": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"enabled": {
"type": "integer"
},
"disabled": {
"type": "integer"
},
"dueCount": {
"type": "integer"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"channels": {
"type": "object",
"properties": {
"in_app": {
"type": "integer"
},
"email": {
"type": "integer"
},
"sms": {
"type": "integer"
},
"webhook": {
"type": "integer"
}
},
"required": [
"in_app",
"email",
"sms",
"webhook"
],
"additionalProperties": false
}
},
"required": [
"total",
"enabled",
"disabled",
"dueCount",
"nextTriggerAt",
"channels"
],
"additionalProperties": false
},
"reminders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"recurrenceMasterId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"channel": {
"type": "string",
"enum": [
"in_app",
"email",
"sms",
"webhook"
]
},
"offsetMinutes": {
"type": "integer",
"minimum": -10080,
"maximum": 10080
},
"isEnabled": {
"type": "boolean"
},
"nextTriggerAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTriggeredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"calendarId",
"calendarEntryId",
"recurrenceMasterId",
"channel",
"offsetMinutes",
"isEnabled",
"nextTriggerAt",
"lastTriggeredAt",
"createdAt",
"updatedAt",
"createdBy",
"deletedAt",
"deletedBy"
],
"additionalProperties": false
}
},
"total": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": [
"calendarId",
"summary",
"reminders",
"total",
"limit",
"offset"
],
"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/admin/calendars/{calendarId}/visit-metrics/reset
Reset tenant admin calendar visit metrics
Reset visit metrics for a calendar from the tenant admin surface and return the updated summary.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityId": {
"type": "string",
"format": "uuid"
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"lastVisitedByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastVisitedByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastResetByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastResetByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetReason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"required": [
"entityId",
"totalVisits",
"lastVisitedAt",
"lastVisitedByActorType",
"lastVisitedByActorId",
"lastResetAt",
"lastResetByActorType",
"lastResetByActorId",
"lastResetReason"
],
"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
Categories
GET
/api/v1/secure/taxonomy/categories/
List categories
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/
Create category
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}
Delete category
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"
]
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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/taxonomy/categories/{id}
Get category
Get category by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/categories/{id}
Update category
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/{id}/entities
List categorized entities
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"
},
"tenantId": {
"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",
"tenantId",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/categories/{id}/i18n
Upsert category translation
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"
},
"tenantId": {
"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",
"tenantId",
"category_id",
"locale",
"name",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/{id}/link
Link category to entity
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"
},
"preferredLanguage": {
"type": "string",
"description": "Locale code for localized responses (e.g., de, en, fr, it)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}/unlink
Unlink category from entity
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
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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/taxonomy/categories/entity
List entity categories
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/export
Export categories
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
Import categories
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
GET
/api/v1/secure/taxonomy/categories/tree
Get category tree
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
Chat
GET
/api/v1/secure/chat/conversations
List conversations for the current user
Retrieve the current user's conversations with pagination support.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/secure/chat/conversations
Start or retrieve a peer conversation
Start a new peer conversation or return the existing conversation for the same participants.
📥 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"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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}
Get a single conversation
Retrieve a single conversation that the current user participates in.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Retrieve the realtime channel name used to subscribe to conversation updates.
📤 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
GET
/api/v1/secure/chat/conversations/{id}/messages
List messages in a conversation
Retrieve paginated message history for a conversation.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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}/messages
Send a message in a conversation
Create and broadcast a new 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"
},
"tenantId": {
"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",
"tenantId",
"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
DELETE
/api/v1/secure/chat/conversations/{id}/messages/{msgId}
Soft-delete a message (own messages only)
Soft-delete a message authored by the current user in a conversation.
📤 RESPONSE 204
Message 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/chat/conversations/{id}/read
Mark all unread messages in a conversation as read
Mark unread messages in a conversation as read for the current user and emit read receipts when needed.
📤 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
POST
/api/v1/secure/chat/conversations/{id}/typing
Emit typing indicator for a conversation
Emit a throttled typing indicator event 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
Retrieve unread message counters across all conversations 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/
List contacts
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"
},
"tenantId": {
"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",
"tenantId",
"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/
Create contact
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete contact
Delete a contact
📤 RESPONSE 204
Contact 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
GET
/api/v1/secure/contacts/{id}
Get contact
Get a contact by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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}
Update contact
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"
},
"tenantId": {
"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",
"tenantId",
"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}/references
List contact references
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/resources/{id}/contacts
List resource contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link resource contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink resource contact
Unlink a contact from a resource
📤 RESPONSE 204
Contact unlinked from resource 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
GET
/api/v1/secure/spaces/{id}/contacts
List space contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link space contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink space contact
Unlink a contact from a space
📤 RESPONSE 204
Contact unlinked from space 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
GET
/api/v1/secure/users/{id}/contacts
List user contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link user contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink user contact
Unlink a contact from a user
📤 RESPONSE 204
Contact unlinked from user 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
GET
/api/v1/secure/users/export
Export contacts
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
Import contacts
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/{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
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
currencies
GET
/api/v1/public/currencies/
List currencies
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}
Get currency by code
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}
List currencies by country
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
Export/Import
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
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/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}
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
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
GET
/api/v1/secure/type-definitions/{id}/export
Export type definition
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",
"calendar",
"user"
],
"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
Export type definitions
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",
"calendar",
"user"
],
"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
GET
/api/v1/secure/type-definitions/export/excel
Export type definitions as spreadsheet
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
Import type definitions
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",
"calendar",
"user"
]
},
"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
POST
/api/v1/secure/type-definitions/import/excel
Import type definitions from spreadsheet
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/services/messaging/templates/{id}/export
Export message template
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
Export message templates
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
Import message templates
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
External APIs
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
Returns recent failures, state alerts, and provider health checks for integration diagnostics.
📤 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/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
Returns paginated integration request log records with optional operation, provider, tenant, and date filters.
📤 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
Returns hourly integration metrics with filtering by tenant, operation, provider, and date range.
📤 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/operations
Integration control-plane operations list
Returns integration operations together with recent request and failure totals.
📤 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
Returns a single integration operation with recent metrics and request log history.
📤 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
Returns the aggregated health, success-rate, and state-event overview for the integration control plane.
📤 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/state
Integration state events
Returns integration state transition events and alerts with optional severity and time filters.
📤 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/tenant-overrides
Integration control-plane tenant overrides list
Returns tenant-specific override rules for integration control-plane operations.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Creates or updates a tenant override for operation enablement, provider ordering, quotas, and config.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"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": [
"tenantId",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Removes a tenant-specific integration override entry by its identifier.
📤 RESPONSE 204
Tenant override 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
Features
GET
/api/v1/secure/features/
List features
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}
Get feature status
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}
Update feature status
Enable or disable a feature (tenant or 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
Bulk update features
Bulk enable/disable features (tenant or 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
Get feature catalog
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
GET
/api/v1/secure/feedback/{entityType}/{entityId}/aggregates
Get entity rating aggregates
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
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- 422 Unprocessable Entity - Validation error with details
→ See StandardErrorResponse
Note: 422 Unprocessable Entity - Validation error with details
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/feedback/{entityType}/{entityId}/ratings
List entity ratings
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"
},
"tenantId": {
"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",
"tenantId",
"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
- 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 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/feedback/{entityType}/{entityId}/reviews
List entity reviews
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"
},
"tenantId": {
"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",
"tenantId",
"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
- 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 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/feedback/rating
Submit rating
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete rating
Delete an existing rating (and its reviews)
📤 RESPONSE 204
Rating 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
PUT
/api/v1/secure/feedback/rating/{id}
Update rating
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"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/secure/feedback/review
Submit review
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete review
Delete an existing review
📤 RESPONSE 204
Review 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
PUT
/api/v1/secure/feedback/review/{id}
Update review
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"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/secure/feedback/review/{id}/flag
Flag review
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"
},
"tenantId": {
"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",
"tenantId",
"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
Files
DELETE
/api/v1/secure/files/{fileId}
Delete file
Delete file
📤 RESPONSE 204
File 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
GET
/api/v1/secure/files/{fileId}
Get file metadata
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
GET
/api/v1/secure/files/{fileId}/download
Download file
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
POST
/api/v1/secure/files/{fileId}/move
Move file
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
GET
/api/v1/secure/files/migrations/
List file migration jobs
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
POST
/api/v1/secure/files/migrations/
Create file migration job
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
DELETE
/api/v1/secure/files/migrations/{jobId}
Cancel file migration job
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 401
- Default Response
→ See StandardErrorResponse
📤 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/files/migrations/{jobId}
Get file migration job
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
POST
/api/v1/secure/files/migrations/{jobId}/start
Start file migration job
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
GET
/api/v1/secure/files/search
Search files
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
Get file statistics
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
POST
/api/v1/secure/files/upload
Upload file
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
Geo-Location
GET
/api/v1/secure/geo/autocomplete
Autocomplete addresses
Return tenant-formatted address suggestions with coordinates for search and selection flows.
📤 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"
},
"formatted_display_name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"type": {
"type": "string"
},
"importance": {
"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"
}
}
}
}
}
},
"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
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/config
Get geo display config
Return the effective geo display configuration for one locale and optional format type.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenantId": {
"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"
},
"tenantId": {
"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
GET
/api/v1/secure/geo/configs
Get geo display configs
Return geo 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"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/secure/geo/geocode
Geocode an address
Convert a freeform or structured address into coordinates and tenant-formatted address details.
📥 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
Reverse geocode coordinates
Convert latitude and longitude into a tenant-formatted address for the requested locale.
📥 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
Group Members
GET
/api/v1/secure/groups/{id}/members
List group members
Retrieve all users currently assigned to a specific group.
📤 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
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
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/
List groups
Retrieve paginated groups with optional tenant, membership, tag, category, and date filters.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
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
GET
/api/v1/secure/groups/{id}
Get group details
Retrieve a specific group and its current configuration by ID.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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",
"tenantId",
"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
Export groups
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
Import groups
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
POST
/api/v1/secure/auth/merge-accounts
Merge secondary auth account
Merges a verified secondary auth account into the current authenticated user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"secondaryAccessToken": {
"type": "string",
"minLength": 1,
"description": "Access token for the secondary account to merge into the current authenticated account"
},
"mergeMode": {
"type": "string",
"enum": [
"move_all",
"safe_only"
],
"description": "Requested merge mode"
},
"dryRun": {
"type": "boolean",
"description": "Whether to calculate the merge plan without applying changes"
}
},
"required": [
"secondaryAccessToken"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"primaryUserId": {
"type": "string",
"format": "uuid"
},
"secondaryUserId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"planned",
"completed",
"failed",
"dry_run"
]
},
"reassignedEntities": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"deletedSecondaryAccount": {
"type": "boolean"
}
},
"required": [
"primaryUserId",
"secondaryUserId",
"status",
"reassignedEntities",
"warnings",
"deletedSecondaryAccount"
],
"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/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
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
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
infotags
GET
/api/v1/public/info-tags/
Get info tags by keys (public)
Fetch system-wide info tag content by keys. Used by <pve-info-tag> component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 <pve-info-tag> component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"tenantId": {
"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
Creates a new tenant-scoped info tag for contextual help content and usage guidance.
📥 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"
},
"tenantId": {
"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
Soft-deletes an info tag so it is no longer returned in tenant help-content lookups.
📤 RESPONSE 204
Info tag 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
GET
/api/v1/secure/info-tags/{id}
Get info tag by ID
Returns a single info tag by UUID when it is accessible to the current tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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
Updates the editable content and localized fields of an existing 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"
},
"tenantId": {
"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
Integration Control Plane
GET
/api/v1/secure/admin/external-apis/control-plane/diagnostics
Integration diagnostics snapshot
Returns recent failures, state alerts, and provider health checks for integration diagnostics.
📤 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/secure/admin/external-apis/control-plane/logs
Integration request telemetry logs
Returns paginated integration request log records with optional operation, provider, tenant, and date filters.
📤 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
Returns hourly integration metrics with filtering by tenant, operation, provider, and date range.
📤 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/operations
Integration control-plane operations list
Returns integration operations together with recent request and failure totals.
📤 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
Returns a single integration operation with recent metrics and request log history.
📤 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
Returns the aggregated health, success-rate, and state-event overview for the integration control plane.
📤 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/state
Integration state events
Returns integration state transition events and alerts with optional severity and time filters.
📤 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/tenant-overrides
Integration control-plane tenant overrides list
Returns tenant-specific override rules for integration control-plane operations.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Creates or updates a tenant override for operation enablement, provider ordering, quotas, and config.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"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": [
"tenantId",
"operation_key",
"enabled"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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
Removes a tenant-specific integration override entry by its identifier.
📤 RESPONSE 204
Tenant override 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
Invitations
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
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenantId",
"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/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": {
"tenantId": {
"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
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"
},
"tenantId": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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",
"tenantId",
"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
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
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"
},
"tenantId": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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",
"tenantId",
"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/
List jobs
Retrieve registered jobs with optional system-job visibility and runtime enrichment when the scheduler is available.
📤 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
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
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
GET
/api/v1/secure/jobs/{name}/history
Get job history
Retrieve paginated execution history for a specific job with optional status, date, and correlation filters.
📤 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"
}
]
},
"tenantId": {
"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/{name}/status
Get job status
Retrieve runtime status, schedule, and execution metrics for a specific job.
📤 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
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
GET
/api/v1/secure/jobs/active
List active jobs
Retrieve the jobs that are currently running for the current tenant or an explicitly requested tenant.
📤 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/history
List job history
Retrieve paginated execution history across jobs with optional job, status, date, and correlation filters.
📤 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"
}
]
},
"tenantId": {
"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/notifications/settings
List job notification settings
Retrieve notification settings for all jobs in the current tenant or for a specific job.
📤 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
GET
/api/v1/secure/jobs/registry
Get job registry
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
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
Activate tenant
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/archive
Archive tenant
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
Get tenant lifecycle history
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenantId": {
"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": [
"tenantId",
"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
POST
/api/v1/secure/tenants/{id}/lifecycle/reactivate
Reactivate tenant
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/suspend
Suspend tenant
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/upgrade
Upgrade tenant
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
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/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/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/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
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/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
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
MCP
GET
/mcp/info
MCP server information
Returns metadata about the PVE Platform MCP server including available tool categories, built-in prompt templates, 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"
},
"instructionsSummary": {
"type": "string"
},
"prompts": {
"type": "object",
"properties": {
"public": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"prompts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"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"
}
}
}
}
}
}
}
}
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
Media
GET
/api/v1/services/media/
List media files
Retrieve paginated media files for the tenant with optional filtering by file type.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"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"
},
"tenantId": {
"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
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}
Get media file details
Retrieve a specific media file together with its stored metadata and current version information.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenantId",
"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"
},
"tenantId": {
"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}/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",
"tenantId",
"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"
},
"tenantId": {
"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/{id}/links
List media file links
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
GET
/api/v1/services/media/{id}/thumbnails
Get media thumbnails
Retrieve generated thumbnail URLs for a specific media file version or its current version.
📤 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
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}/versions
List media file versions
Retrieve the version history for a specific media file.
📤 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
GET
/api/v1/services/media/entity/{entityType}/{entityId}/media
List entity media
Retrieve media linked to a specific entity with optional private-media filtering.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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/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",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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
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",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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
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",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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
Get main entity media
Retrieve the primary media item linked to a specific entity.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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
POST
/api/v1/services/media/upload
Upload media file
Upload media file with multipart/form-data
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenantId",
"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"
},
"tenantId": {
"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
Messaging
POST
/api/v1/services/messaging/{id}/cancel
Cancel message
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
GET
/api/v1/services/messaging/{id}/provider-logs
Get provider logs
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"
},
"tenantId": {
"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
Retry message
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
GET
/api/v1/services/messaging/{id}/status
Get message status
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
POST
/api/v1/services/messaging/preview
Preview message template
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/rate-limits
Get rate limit statistics
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
DELETE
/api/v1/services/messaging/rate-limits/config
Reset rate limit configuration
Reset rate limit configuration to system defaults
📤 RESPONSE 204
Rate limit configuration reset 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
GET
/api/v1/services/messaging/rate-limits/config
Get rate limit configuration
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
Update rate limit configuration
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
GET
/api/v1/services/messaging/recent
List recent messages
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
POST
/api/v1/services/messaging/send
Send message
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/stats
Get messaging statistics
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/templates
List message templates
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
Create message template
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
DELETE
/api/v1/services/messaging/templates/{id}
Delete message template
Delete a message template (deactivates all versions)
📤 RESPONSE 204
Template 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
PUT
/api/v1/services/messaging/templates/{id}
Update message template
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
GET
/api/v1/services/messaging/templates/{id}/export
Export message template
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
Export message templates
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
Import message templates
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
GET
/api/v1/secure/files/migrations/
List file migration jobs
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
POST
/api/v1/secure/files/migrations/
Create file migration job
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
DELETE
/api/v1/secure/files/migrations/{jobId}
Cancel file migration job
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 401
- Default Response
→ See StandardErrorResponse
📤 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/files/migrations/{jobId}
Get file migration job
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
POST
/api/v1/secure/files/migrations/{jobId}/start
Start file migration job
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
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": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant ID to set as default"
}
},
"required": [
"tenantId"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"defaultTenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"success",
"defaultTenantId"
],
"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
POST
/api/v1/secure/auth/switch-tenant
Switch tenant
Switch the active tenant for the current session
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Target tenant ID to switch to"
}
},
"required": [
"tenantId"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"type": "string"
},
"tenantSlug": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"success",
"tenantId",
"tenantName",
"tenantSlug",
"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
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": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"member",
"guest",
"system_admin"
]
}
},
"required": [
"tenantId",
"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
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"
},
"tenantId": {
"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"
},
"tenantName": {
"type": "string"
},
"tenantSlug": {
"type": "string"
}
},
"required": [
"user_id",
"tenantId",
"role",
"tenantName",
"tenantSlug"
],
"additionalProperties": false
}
},
"activeTenantId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"defaultTenantId": {
"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
OAuth
POST
/api/v1/public/auth/oauth/exchange
Exchange OAuth client callback code
Completes Track 2 OAuth authentication from a client-owned callback route without exposing direct Supabase auth setup to the frontend
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"description": "Authorization code returned to the client-owned callback route"
},
"pveState": {
"type": "string",
"format": "uuid",
"description": "PVE-issued OAuth state ID returned in the client-owned callback route"
}
},
"required": [
"code",
"pveState"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"authenticated",
"registration_required"
]
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"requiresPostAuthFlow": {
"type": "boolean"
},
"user": {
"anyOf": [
{
"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
},
{
"type": "null"
}
]
},
"registration": {
"anyOf": [
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"avatarUrl": {
"type": "string",
"format": "uri"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"email"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"status",
"provider",
"accessToken",
"refreshToken",
"requiresPostAuthFlow"
],
"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/auth/oauth/initiate
Initiate OAuth client callback flow
Starts Track 2 OAuth authentication for client-owned callback routes
📥 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",
"minLength": 1,
"description": "Client-owned callback URI (https://, chrome-extension://, or app:// depending on configuration)"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Optional tenant ID for multi-tenant login"
},
"clientType": {
"type": "string",
"enum": [
"web",
"extension",
"desktop",
"mobile"
],
"description": "Client type initiating the OAuth broker flow"
}
},
"required": [
"provider",
"redirectUrl",
"clientType"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"oauthUrl": {
"type": "string",
"description": "OAuth provider authorization URL"
},
"provider": {
"type": "string",
"enum": [
"google",
"microsoft",
"apple",
"facebook",
"github"
]
},
"clientType": {
"type": "string",
"enum": [
"web",
"extension",
"desktop",
"mobile"
]
},
"redirectMode": {
"type": "string",
"enum": [
"client_callback"
]
},
"stateId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"oauthUrl",
"provider",
"clientType",
"redirectMode",
"stateId",
"expiresAt"
],
"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/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
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"
},
"capabilities": {
"type": "object",
"properties": {
"server_callback": {
"type": "boolean",
"description": "Whether the provider supports the legacy backend callback flow"
},
"client_callback": {
"type": "boolean",
"description": "Whether the provider supports the Track 2 client callback broker flow"
},
"native_mobile": {
"type": "boolean",
"description": "Whether the provider is recommended for native mobile SDK flows"
}
},
"required": [
"server_callback",
"client_callback",
"native_mobile"
],
"additionalProperties": false
}
},
"required": [
"id",
"name",
"enabled",
"capabilities"
],
"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
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
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/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
Phone Validation (Public)
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
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
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
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
phone-codes
GET
/api/v1/public/phone-codes/
List phone codes
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/{country}
Get phone code by country
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/phone-codes/search
Search phone codes
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
Profile
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
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
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
public
GET
/api/v1/public/currencies/
List currencies
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}
Get currency by code
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}
List currencies by country
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/info-tags/
Get info tags by keys (public)
Fetch system-wide info tag content by keys. Used by <pve-info-tag> component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 <pve-info-tag> component.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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/public/phone-codes/
List phone codes
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/{country}
Get phone code by country
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/phone-codes/search
Search phone codes
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
Public
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
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenantId",
"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/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": {
"tenantId": {
"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
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
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}
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
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
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
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
Realtime
GET
/api/v1/secure/auth/client-config/realtime
Get secure realtime client configuration
Returns runtime realtime configuration for authenticated clients without requiring frontend build-time Supabase environment variables
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"supabaseUrl": {
"type": "string",
"format": "uri"
},
"supabaseAnonKey": {
"type": "string"
}
},
"required": [
"supabaseUrl",
"supabaseAnonKey"
],
"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/services/realtime/channels
List realtime channels
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"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/services/realtime/channels
Create realtime channel
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"
},
"tenantId": {
"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",
"tenantId",
"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
DELETE
/api/v1/services/realtime/channels/{id}
Delete realtime channel
Soft delete a realtime channel
📤 RESPONSE 204
Realtime channel 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
GET
/api/v1/services/realtime/channels/{id}
Get realtime channel
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"
},
"tenantId": {
"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",
"tenantId",
"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
List missed realtime events
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 in an existing tenant context. Provide tenantId, X-Tenant-ID, or use a mapped tenant domain.
📥 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
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant context for self-registration. Required unless the tenant is resolved from X-Tenant-ID or a mapped custom domain."
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"userId": {
"type": "string",
"format": "uuid"
},
"requiresVerification": {
"type": "boolean"
},
"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"
}
},
"required": [
"id",
"email",
"displayName",
"tenantId"
],
"additionalProperties": false
},
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"domain": {
"type": "string"
}
},
"required": [
"id",
"name",
"slug",
"domain"
],
"additionalProperties": false
}
},
"required": [
"message",
"userId",
"requiresVerification",
"user",
"tenant"
],
"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 Members
GET
/api/v1/secure/resources/{id}/members
List resource members
Retrieve all members assigned to a specific resource and their current roles.
📤 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"
}
]
},
"role": {
"type": "string",
"enum": [
"admin",
"manager",
"reader"
]
},
"created_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"user_id",
"role"
],
"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}/members
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}/members/{userId}
No summary
📤 RESPONSE 204
Resource member removed 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
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"
},
"tenantId": {
"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"
},
"approval_mode": {
"type": "string",
"enum": [
"resource",
"target_space"
]
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resource_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"target_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requested_by_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"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",
"tenantId",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"approval_mode",
"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
List resource move requests
Retrieve resource move requests with optional filtering by status and resource.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"approval_mode": {
"type": "string",
"enum": [
"resource",
"target_space"
]
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resource_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"target_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requested_by_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"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",
"tenantId",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"approval_mode",
"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
DELETE
/api/v1/secure/resources/resource-requests/{id}
No summary
📤 RESPONSE 204
Move request cancelled 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/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"
},
"tenantId": {
"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"
},
"approval_mode": {
"type": "string",
"enum": [
"resource",
"target_space"
]
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resource_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"target_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requested_by_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"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",
"tenantId",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"approval_mode",
"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"
},
"tenantId": {
"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"
},
"approval_mode": {
"type": "string",
"enum": [
"resource",
"target_space"
]
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resource_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"source_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"target_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requested_by_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"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",
"tenantId",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"approval_mode",
"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
Resources
GET
/api/v1/secure/resources/
List resources
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"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (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 additional languages (excludes base language)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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)"
},
"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"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"language",
"translations_i18n",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"currentLocation",
"mainMedia"
],
"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/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"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"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"
}
]
},
"categoryIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tagIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translationsI18n": {
"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"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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}
Get resource details
Retrieve a specific resource with localized fields, current location metadata, and the current visit metric summary fields. The response can include totalVisits and lastVisitedAt when entity visit metrics are enabled, but it does not increment the counter. Clients should call POST /api/v1/secure/resources/{id}/visit-metrics/track asynchronously after the record is actually displayed to the user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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/resources/{id}
Update resource
Update a resource and return the enriched resource payload.
📥 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"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"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"
}
]
},
"categoryIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"tagIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
]
},
"translationsI18n": {
"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"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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/{id}/categories
List resource categories
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"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
Link resource category
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Unlink resource category
Unlink a category from a resource
📤 RESPONSE 204
Category unlinked from resource
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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
List resource contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link resource contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink resource contact
Unlink a contact from a resource
📤 RESPONSE 204
Contact unlinked from resource 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/resources/{id}/detach
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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}/order-top
Move resource to top order
Assigns the next highest custom order value to the resource so it appears at the top of resource list and nearby results.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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/resources/{id}/promotion
Update resource promotion
Assign, update, or clear the promotion rank and active window for a resource.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
]
},
"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 (e.g., en, de, fr, it)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder"
],
"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/{id}/tags
List resource tags
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"
},
"tenantId": {
"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",
"tenantId",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"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
Link resource tag
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Unlink resource tag
Unlink a tag from a resource
📤 RESPONSE 204
Tag unlinked from resource
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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}/visit-metrics/reset
Reset resource visit metrics
Resets the aggregated visit metrics counters for a single resource.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityId": {
"type": "string",
"format": "uuid"
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"lastVisitedByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastVisitedByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastResetByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastResetByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetReason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"required": [
"entityId",
"totalVisits",
"lastVisitedAt",
"lastVisitedByActorType",
"lastVisitedByActorId",
"lastResetAt",
"lastResetByActorType",
"lastResetByActorId",
"lastResetReason"
],
"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}/visit-metrics/track
Track resource detail visit
Records a resource detail visit explicitly. Call this asynchronously after the resource record is displayed to the user. Use GET /api/v1/secure/resources/{id} for the current summary fields and POST this endpoint only when the app decides the view counts as a visit.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityId": {
"type": "string",
"format": "uuid"
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"lastVisitedByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastVisitedByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastResetByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastResetByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetReason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"required": [
"entityId",
"totalVisits",
"lastVisitedAt",
"lastVisitedByActorType",
"lastVisitedByActorId",
"lastResetAt",
"lastResetByActorType",
"lastResetByActorId",
"lastResetReason"
],
"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/export
Export resources
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
Import resources
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/nearby
Search nearby resources
Use this route for GPS, GIS, geo, geolocation, and near-me resource discovery with PostGIS-native filtering, distance ordering, and page-scoped enrichment.
📤 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": [
"system",
"custom"
]
},
"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 (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 additional languages (excludes base language)"
},
"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"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this resource; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"current_space_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"distanceMeters": {
"type": "number",
"description": "Distance from the supplied reference coordinates in meters"
},
"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
}
},
"mediaFileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Linked media file ids for the nearby result page when requested; empty when omitted."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this resource. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"type",
"name",
"language",
"translations_i18n",
"status",
"typeDefinitionId",
"typeName",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"space_id",
"current_space_name",
"distanceMeters",
"currentLocation",
"categories",
"tags",
"mediaFileIds",
"created_at",
"updated_at",
"mainMedia"
],
"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
S3
GET
/api/v1/secure/storage/s3/
List S3 storage configurations
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"
},
"tenantId": {
"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",
"tenantId",
"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/
Create S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete S3 storage configuration
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
GET
/api/v1/secure/storage/s3/{id}
Get S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Update S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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/{id}/metrics
Get S3 usage metrics
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
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
Rotate S3 credentials
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
Get S3 rotation history
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
POST
/api/v1/secure/storage/s3/{id}/test
Test S3 connection
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
GET
/api/v1/secure/storage/s3/cost-estimate
Estimate S3 cost
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/encryption-types
List S3 encryption types
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/regions
List S3 regions
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
Search
GET
/api/v1/secure/search/
Run global search
Search across supported entities using the provided full-text query.
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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_enabled": {
"type": "boolean"
},
"cors_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_allow_credentials": {
"type": "boolean"
},
"cors_max_age": {
"type": "number"
},
"csrf_enabled": {
"type": "boolean"
},
"csrf_token_expiry": {
"type": "number"
},
"csrf_cookie_name": {
"type": "string"
},
"csrf_header_name": {
"type": "string"
},
"csp_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"
},
"x_xss_protection": {
"type": "string"
},
"referrer_policy": {
"type": "string"
}
},
"additionalProperties": false
}
📤 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/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/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/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
},
"tenantId": {
"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/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
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/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
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
Settings
GET
/api/v1/secure/settings/
List settings
Retrieve the current backend settings available to the authenticated tenant.
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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
List space members
Retrieve all members assigned to a specific space and their current roles.
📤 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/
List spaces
Retrieve paginated spaces with optional filtering by type, status, taxonomy, manageability, and location.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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)"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters",
"mainMedia"
],
"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": 2,
"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",
"retired",
"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"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 (e.g., en, de, fr, it)"
},
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters"
],
"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}
Get space details
Retrieve a specific space with localized fields, optional distance context, and visit metrics enrichment.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 (e.g., en, de, fr, it)"
},
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters"
],
"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": 2,
"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",
"retired",
"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"
},
"tenantId": {
"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 (e.g., en, de, fr, it)"
},
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters"
],
"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}/categories
List space categories
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"
},
"tenantId": {
"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",
"tenantId",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"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
Link space category
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Unlink space category
Unlink a category from a space
📤 RESPONSE 204
Category unlinked from space
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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
List space contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link space contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink space contact
Unlink a contact from a space
📤 RESPONSE 204
Contact unlinked from space 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/spaces/{id}/order-top
Move space to top order
Assigns the next highest custom order value to the space so it appears at the top of space list and nearby results.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 (e.g., en, de, fr, it)"
},
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters"
],
"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}/promotion
Update space promotion
Assign, update, or clear the promotion rank and active window for a space.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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 (e.g., en, de, fr, it)"
},
"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",
"retired",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"PositionDynamic",
"PositionFix",
"CommercialAdd"
],
"default": "None",
"description": "Promotion presentation mode. None disables promotion styling; position modes can optionally combine with promotionRank."
},
"promotionRank": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Purchased absolute list rank for this space; null when not promoted"
},
"promotionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion start date; null means active immediately"
},
"promotionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Promotion end date; null means promotion does not expire"
},
"customOrder": {
"type": "integer",
"minimum": 1,
"description": "Custom descending order rank for manual list and nearby ordering. Higher values sort earlier when clients order descending."
},
"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"
},
"distanceMeters": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Distance from the supplied reference coordinates in meters; null when no reference coordinates were provided or the space has no location"
},
"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
}
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"mainMedia": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Main media link for this space. Use media entity endpoints for the full media collection."
}
},
"required": [
"id",
"tenantId",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"promotionType",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"distanceMeters"
],
"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}/tags
List space tags
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"
},
"tenantId": {
"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",
"tenantId",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"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
Link space tag
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Unlink space tag
Unlink a tag from a space
📤 RESPONSE 204
Tag unlinked from space
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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}/visit-metrics/reset
Reset space visit metrics
Resets the aggregated visit metrics counters for a single space.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entityId": {
"type": "string",
"format": "uuid"
},
"totalVisits": {
"type": "integer",
"minimum": 0,
"description": "Current aggregated visit counter returned in detail responses and visit summary payloads."
},
"lastVisitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp of the most recently counted visit in the aggregated summary. The increment trigger depends on the entity-specific REST workflow."
},
"lastVisitedByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastVisitedByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastResetByActorType": {
"anyOf": [
{
"type": "string",
"enum": [
"user",
"api_key",
"app_account"
]
},
{
"type": "null"
}
]
},
"lastResetByActorId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastResetReason": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
]
}
},
"required": [
"entityId",
"totalVisits",
"lastVisitedAt",
"lastVisitedByActorType",
"lastVisitedByActorId",
"lastResetAt",
"lastResetByActorType",
"lastResetByActorId",
"lastResetReason"
],
"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/export
Export spaces
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
Import spaces
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
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/buckets/
List storage buckets
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"
},
"tenantId": {
"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/
Create storage bucket
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"
},
"tenantId": {
"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/{bucket_name}/download/{*}
Download bucket file
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
GET
/api/v1/secure/storage/buckets/{bucket_name}/files
List bucket files
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
Upload bucket file
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
DELETE
/api/v1/secure/storage/buckets/{bucket_name}/files/{*}
Delete bucket file
Delete file from storage bucket
📤 RESPONSE 204
Storage file 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
GET
/api/v1/secure/storage/buckets/{bucket_name}/thumbnail/{*}
Get file thumbnail
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
DELETE
/api/v1/secure/storage/buckets/{id}
Delete storage bucket
Delete storage bucket
📤 RESPONSE 204
Storage bucket 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
GET
/api/v1/secure/storage/buckets/{id}
Get storage bucket details
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"
},
"tenantId": {
"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}
Update storage bucket
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
GET
/api/v1/secure/storage/buckets/providers
List storage providers
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
Get storage provider statistics
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"
},
"tenantId": {
"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/distribution-config
Get distribution configuration
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
Update distribution configuration
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
GET
/api/v1/secure/storage/policies
List storage policies
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/s3/
List S3 storage configurations
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"
},
"tenantId": {
"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",
"tenantId",
"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/
Create S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete S3 storage configuration
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
GET
/api/v1/secure/storage/s3/{id}
Get S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Update S3 storage configuration
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"
},
"tenantId": {
"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",
"tenantId",
"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/{id}/metrics
Get S3 usage metrics
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
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
Rotate S3 credentials
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
Get S3 rotation history
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
POST
/api/v1/secure/storage/s3/{id}/test
Test S3 connection
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
GET
/api/v1/secure/storage/s3/cost-estimate
Estimate S3 cost
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/encryption-types
List S3 encryption types
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/regions
List S3 regions
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/system/stats
Get system storage stats
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/system/status
Get system storage status
Get tenant system storage status (quota, usage, available)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
},
"required": [
"tenantId",
"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
POST
/api/v1/secure/storage/test-upload
Test storage upload
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
PATCH
/api/v1/secure/tenants/{id}/system-storage
Update tenant system storage
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": {
"tenantId": {
"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/secure/features/catalog
Get feature catalog
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
GET
/api/v1/secure/iam/
Get IAM overview
Retrieve the current user's IAM overview including groups, permissions, and admin flags.
📤 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/can
Check entity permission
Check whether the current user can perform a read or write action on a specific space or resource.
📤 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/iam/me/permissions
List effective permissions
Retrieve the flattened list of effective permissions for the current user.
📤 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/resources/manageable
List manageable resources
Retrieve the resources the current user can manage within their accessible spaces.
📤 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/me/spaces
List user space memberships
Retrieve the spaces the current user belongs to together with their membership roles.
📤 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
List manageable spaces
Retrieve the spaces the current user can manage as a tenant admin or space manager.
📤 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
POST
/api/v1/system/dispatcher/alerts/{id}/acknowledge
Acknowledge dispatcher alert
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/system/dispatcher/health
Get dispatcher health
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"
}
}
}
}
}
}
POST
/api/v1/system/dispatcher/run
Run dispatcher jobs
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/status
Get dispatcher status
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
GET
/api/v1/system/health
Get system health
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
Get system information
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
Tags
GET
/api/v1/secure/taxonomy/tags/
List tags
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"
},
"tenantId": {
"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",
"tenantId",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"returnedCount": {
"type": "number"
},
"total": {
"type": "number"
}
},
"required": [
"data",
"returnedCount"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/tags/{id}
Delete tag
Delete tag (admin only)
📤 RESPONSE 204
Tag deleted successfully
GET
/api/v1/secure/taxonomy/tags/{id}
Get tag
Get tag by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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/{id}/entities
List tagged entities
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"
},
"tenantId": {
"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",
"tenantId",
"tag_id",
"entity_type",
"entity_id",
"created_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"
},
"tenantId": {
"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",
"tenantId",
"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}/unlink
Unlink tag from entity
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
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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/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"
},
"tenantId": {
"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",
"tenantId",
"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/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"
},
"tenantId": {
"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",
"tenantId",
"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"
}
}
}
}
}
GET
/api/v1/secure/taxonomy/tags/cloud
Get tag cloud
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
}
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"
},
"tenantId": {
"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",
"tenantId",
"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/entity
List entity tags
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"
},
"tenantId": {
"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",
"tenantId",
"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
Export tags
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
Import tags
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
POST
/api/v1/secure/taxonomy/tags/link
Link tag to entity
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"
},
"tenantId": {
"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",
"tenantId",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/link/bulk
Bulk link tags
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"
},
"tenantId": {
"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",
"tenantId",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
Tenant Domains
GET
/api/v1/secure/tenant-domains/
List tenant domains
Retrieve all custom domains configured for the authenticated tenant.
📤 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"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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/
Create tenant domain
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"
],
"description": "Type of domain: api"
},
"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"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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
GET
/api/v1/secure/tenant-domains/{id}
Get tenant domain details
Retrieve configuration and verification status for a specific tenant domain.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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}/verification-instructions
Get domain verification instructions
Retrieve the DNS records and steps required to verify a specific tenant domain.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Domain to configure"
},
"domain_type": {
"type": "string",
"enum": [
"api"
],
"description": "Type of domain: api"
},
"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
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
Tenant Metrics
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
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
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"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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
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"
},
"tenantId": {
"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": [
"tenantId",
"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"
},
"tenantId": {
"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": [
"tenantId",
"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"
},
"tenantId": {
"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": [
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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/
List tenants
Retrieve the tenants visible to the current user. System admins can see all tenants; other users see only their own tenant.
📤 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
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}
Get tenant details
Retrieve the configuration and metadata for a specific tenant.
📤 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
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}/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
GET
/api/v1/secure/tenants/{id}/domains
List tenant domains
Returns custom domains configured 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",
"description": "Domain configuration unique identifier"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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/tenants/{id}/domains
Create tenant domain
Creates a custom domain entry for the specified tenant and starts its managed lifecycle.
📥 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"
],
"description": "Type of domain: api"
},
"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"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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/tenants/{id}/domains/{domainId}
Delete tenant domain
Deletes a custom domain from the specified tenant configuration.
📤 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
GET
/api/v1/secure/tenants/{id}/domains/{domainId}
Get tenant domain
Returns a single custom domain configured for the specified tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Domain configuration unique identifier"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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/tenants/{id}/domains/{domainId}
Update tenant domain
Updates the hostname, status, or verification-related settings for a tenant domain.
📥 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"
},
"tenantId": {
"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"
],
"description": "Type of domain: api (platform API root, environment-specific target resolved by deployment)"
},
"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",
"tenantId",
"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/tenants/{id}/domains/{domainId}/verification-instructions
Get tenant domain verification instructions
Returns DNS or platform setup instructions required to complete tenant domain verification.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Domain to configure"
},
"domain_type": {
"type": "string",
"enum": [
"api"
],
"description": "Type of domain: api"
},
"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
POST
/api/v1/secure/tenants/{id}/domains/{domainId}/verify
Verify tenant domain
Runs the domain verification workflow and returns the latest verification result.
📤 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/tenants/{id}/env
Export tenant environment configuration
Export the tenant configuration as a downloadable .env 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/tenants/{id}/info
Get tenant onboarding information
Retrieve comprehensive tenant onboarding details including tenant, admin, API, group, and space information.
📤 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}/json
Export tenant JSON configuration
Export the tenant configuration as a downloadable JSON 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/tenants/{id}/language-sync-status
Get language sync status
Retrieve the current status of a tenant language sync job or list recent sync jobs for the tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
]
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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"
},
"tenantId": {
"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",
"tenantId",
"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
POST
/api/v1/secure/tenants/{id}/lifecycle/activate
Activate tenant
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/archive
Archive tenant
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
Get tenant lifecycle history
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenantId": {
"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": [
"tenantId",
"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
POST
/api/v1/secure/tenants/{id}/lifecycle/reactivate
Reactivate tenant
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/suspend
Suspend tenant
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/upgrade
Upgrade tenant
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
GET
/api/v1/secure/tenants/{id}/log-retention
Get tenant log retention policy
Retrieve the current log retention policy for the specified tenant, including the default when no explicit setting exists.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"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": {
"tenantId": {
"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
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
DELETE
/api/v1/secure/tenants/{id}/storage-config
Delete tenant storage configuration
Delete tenant storage configuration (revert to default Supabase)
📤 RESPONSE 204
Tenant storage configuration 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
GET
/api/v1/secure/tenants/{id}/storage-config
Get tenant storage configuration
Get tenant storage provider configuration (credentials masked)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"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
Update tenant storage configuration
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
PATCH
/api/v1/secure/tenants/{id}/system-storage
Update tenant system storage
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": {
"tenantId": {
"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
GET
/api/v1/secure/tenants/{id}/translation-coverage
Get translation coverage
Retrieve translation coverage across spaces, resources, categories, and tags for a tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total entities in this tenant scope"
},
"translated": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one additional-language translation"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"percentage"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total entities in this tenant scope"
},
"translated": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one additional-language translation"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"percentage"
],
"additionalProperties": false
},
"categories": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total entities in this tenant scope"
},
"translated": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one additional-language translation"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"percentage"
],
"additionalProperties": false
},
"tags": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total entities in this tenant scope"
},
"translated": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one additional-language translation"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"percentage"
],
"additionalProperties": false
}
},
"required": [
"spaces",
"resources",
"categories",
"tags"
],
"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
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/{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
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
Type Definitions
GET
/api/v1/secure/type-definitions/
List type definitions
Retrieve type definitions with optional filtering by target entity type, type name, and system-type visibility.
📤 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": "Legacy category classification used to infer appliesTo when appliesTo is omitted",
"maxLength": 100
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource",
"calendar",
"user"
],
"description": "Explicit entity type this definition applies to"
},
"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
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}
Get type definition details
Retrieve a specific type definition and its schema details by ID.
📤 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
GET
/api/v1/secure/type-definitions/{id}/export
Export type definition
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",
"calendar",
"user"
],
"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
Export type definitions
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",
"calendar",
"user"
],
"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
GET
/api/v1/secure/type-definitions/export/excel
Export type definitions as spreadsheet
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
Import type definitions
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",
"calendar",
"user"
]
},
"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
POST
/api/v1/secure/type-definitions/import/excel
Import type definitions from spreadsheet
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
Get user permissions
Retrieve the effective permission list for a specific user within the current tenant.
📤 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/
List users
Retrieve paginated users with optional search and tenant filtering based on the caller's access scope.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"emailConfirmedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp from Supabase Auth when the user email was confirmed"
},
"emailVerificationStatus": {
"type": "string",
"enum": [
"verified",
"pending",
"not_configured"
],
"description": "Current tenant confirmation-flow state for the user email"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"email",
"status",
"avatar_source",
"type_definition_id",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"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"
]
},
"settings": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"emailConfirmedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp from Supabase Auth when the user email was confirmed"
},
"emailVerificationStatus": {
"type": "string",
"enum": [
"verified",
"pending",
"not_configured"
],
"description": "Current tenant confirmation-flow state for the user email"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"email",
"status",
"avatar_source",
"type_definition_id",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"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}
Get user details
Retrieve the full profile information for a specific user in the current tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"emailConfirmedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp from Supabase Auth when the user email was confirmed"
},
"emailVerificationStatus": {
"type": "string",
"enum": [
"verified",
"pending",
"not_configured"
],
"description": "Current tenant confirmation-flow state for the user email"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"email",
"status",
"avatar_source",
"type_definition_id",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"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"
]
},
"settings": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"emailConfirmedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp from Supabase Auth when the user email was confirmed"
},
"emailVerificationStatus": {
"type": "string",
"enum": [
"verified",
"pending",
"not_configured"
],
"description": "Current tenant confirmation-flow state for the user email"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"email",
"status",
"avatar_source",
"type_definition_id",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"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}/contacts
List user contacts
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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
Link user contact
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"
},
"tenantId": {
"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"
},
"tenantId": {
"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",
"tenantId",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenantId",
"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}
Unlink user contact
Unlink a contact from a user
📤 RESPONSE 204
Contact unlinked from user 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
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"
},
"tenantId": {
"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"
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Current version number of the media file used for cache-busting and optimistic refreshes"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnail variants are available for this 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",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"type_definition_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Type definition controlling validation of the user settings payload"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-validated user-specific application settings and preferences"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"emailConfirmedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Timestamp from Supabase Auth when the user email was confirmed"
},
"emailVerificationStatus": {
"type": "string",
"enum": [
"verified",
"pending",
"not_configured"
],
"description": "Current tenant confirmation-flow state for the user email"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"email",
"status",
"avatar_source",
"type_definition_id",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"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
POST
/api/v1/secure/users/{id}/reset-password
Reset user password
Generate a temporary password for a user. The current password stops working immediately.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"password": {
"type": "string",
"minLength": 12,
"description": "Temporary password returned once after an admin-initiated reset"
}
},
"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
Webhooks
GET
/api/v1/secure/webhooks/event-types
List webhook event types
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
List webhook subscriptions
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"
},
"tenantId": {
"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",
"tenantId",
"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
Create webhook subscription
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"
},
"tenantId": {
"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",
"tenantId",
"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}
Delete webhook subscription
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
GET
/api/v1/secure/webhooks/subscriptions/{id}
Get webhook subscription
Get a specific webhook subscription
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"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",
"tenantId",
"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}
Update webhook subscription
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"
},
"tenantId": {
"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",
"tenantId",
"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/subscriptions/{id}/logs
Get webhook delivery logs
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
Get webhook delivery statistics
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
POST
/api/v1/secure/webhooks/subscriptions/{id}/test
Test webhook subscription
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
POST
/api/v1/webhooks/inbound/sendgrid
Handle SendGrid webhook
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
Handle Twilio webhook
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
Shared Schemas
Reusable component schemas referenced by multiple routes, including the standard error envelope shared across the API.
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
}