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/external-apis/openrouter/models
List OpenRouter models
Returns the current OpenRouter model catalog for text or image tasks so the admin GUI can restrict selection to supported models only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"task": {
"type": "string",
"enum": [
"text",
"image"
]
},
"total": {
"type": "integer"
},
"models": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Canonical OpenRouter model identifier."
},
"name": {
"type": "string",
"description": "Human-readable model name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"image_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"request_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"is_free": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"description",
"context_length",
"prompt_price",
"completion_price",
"image_price",
"request_price",
"is_free"
],
"additionalProperties": false
}
}
},
"required": [
"task",
"total",
"models"
],
"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/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/default-tenant-storage/stats
Get default tenant storage stats
Get default tenant 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}/default-tenant-storage
Update tenant default storage
Update tenant default storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Must remain true for default tenant storage"
},
"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 system storage 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
Admin Notifications
GET
/api/v1/secure/admin/notifications/deliveries
List tenant notification deliveries
List notification deliveries in the current tenant for diagnostics and support.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"userNotificationId",
"notificationEventId",
"tenantId",
"userId",
"channel",
"status",
"attemptCount",
"scheduledFor",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"userNotificationId": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"deviceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"sent",
"delivered",
"failed",
"suppressed",
"canceled",
"dead_letter"
]
},
"providerMessageId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attemptCount": {
"type": "integer",
"minimum": 0
},
"lastErrorCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastErrorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scheduledFor": {
"type": "string",
"format": "date-time"
},
"processedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"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/admin/notifications/overview
Get tenant notification overview
Return tenant-admin notification delivery counts and backlog summary.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"queuedCount",
"failedCount",
"deliveryCountsByChannel",
"deliveryCountsByStatus"
],
"properties": {
"queuedCount": {
"type": "integer",
"minimum": 0
},
"failedCount": {
"type": "integer",
"minimum": 0
},
"deliveryCountsByChannel": {
"type": "array",
"items": {
"type": "object",
"required": [
"channel",
"count"
],
"properties": {
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"count": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}
},
"deliveryCountsByStatus": {
"type": "array",
"items": {
"type": "object",
"required": [
"status",
"count"
],
"properties": {
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"sent",
"delivered",
"failed",
"suppressed",
"canceled",
"dead_letter"
]
},
"count": {
"type": "integer",
"minimum": 0
}
},
"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/secure/admin/notifications/preferences
List tenant notification preferences
List tenant-default or user-override notification preferences from the tenant-admin surface.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"scope",
"category",
"channel",
"enabled",
"quietHours",
"rules",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"scope": {
"type": "string",
"enum": [
"tenant_default",
"user_override"
]
},
"category": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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/admin/notifications/preferences
Update tenant notification preferences
Update tenant-default or user-override notification preferences from the tenant-admin surface.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"preferences"
],
"properties": {
"preferences": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"category",
"channel",
"enabled"
],
"properties": {
"category": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"scope": {
"type": "string",
"enum": [
"tenant_default",
"user_override"
]
},
"userId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"scope",
"category",
"channel",
"enabled",
"quietHours",
"rules",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"scope": {
"type": "string",
"enum": [
"tenant_default",
"user_override"
]
},
"category": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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
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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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",
"additionalProperties": true,
"description": "Provider-specific configuration (JSONB)"
},
"auth_config": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"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 a space, resource, tag, or category and update translations_i18n in the database. When target_languages is omitted, the endpoint fills only missing translated content for tenant-enabled additional languages and leaves existing translated fields unchanged. When target_languages is provided, the selected languages are translated and existing target content is overwritten. The base language is never persisted in translations_i18n.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tag",
"category"
],
"description": "Entity kind to translate. For your main use case, use space or resource."
},
"entity_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the space, resource, tag, or category to translate."
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Optional source language override. Defaults to the entity base language, then falls back to detected translation content."
},
"target_languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"description": "Optional explicit target language list. When omitted, the endpoint fills only missing translated fields for tenant-enabled additional languages. When provided, the selected languages are translated and existing target content is overwritten."
}
},
"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/entity-type
Translate all entities of a taxonomy type
Translate all categories or tags for the current tenant in language-first batches. When target_languages is omitted, the endpoint fills only missing tenant-language content.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tag",
"category"
],
"description": "Bulk translation supports spaces, resources, categories, and tags."
},
"entity_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Optional subset of entity ids to translate. When omitted, all tenant entities of the selected type are considered."
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Optional source language override. Defaults to each entity base language."
},
"target_languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"description": "Optional explicit target language list. When omitted, the endpoint fills missing tenant languages only."
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entity_type": {
"type": "string"
},
"entities_total": {
"type": "number"
},
"entities_translated": {
"type": "number"
},
"languages_translated": {
"type": "array",
"items": {
"type": "string"
}
},
"provider_used": {
"type": "string"
},
"batches_processed": {
"type": "number"
}
},
"required": [
"entity_type",
"entities_total",
"entities_translated",
"languages_translated",
"provider_used",
"batches_processed"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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 entity-style i18n JSON with language keys and name/description fields. When target_languages is omitted, all tenant-enabled languages except the source language are used.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"i18n_data"
],
"properties": {
"i18n_data": {
"type": "object",
"description": "Language-keyed translation input. Current backend support is entity-style content with name/description fields, not arbitrary nested resource-file trees.",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
},
"source_language": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Optional source language. Auto-detected from the first populated language when omitted."
},
"target_languages": {
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"description": "Optional explicit target language list. When omitted, the service uses all tenant-enabled languages except the source language."
}
},
"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,
"pattern": ".*\\S.*"
},
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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- `qrCodes`: Access to QR code lookup, management, deletion, and assignment/linking\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 \"qrCodes\": { \"read\": true, \"write\": false, \"delete\": false, \"assign\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n```"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Enable MCP mutating operations for this key (default: false)"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\", \"10.0.0.1\"])"
},
"device_fingerprint": {
"type": "string",
"description": "Optional device fingerprint for mobile attestation"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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- `qrCodes`: Access to QR code lookup, management, deletion, and assignment/linking\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 \"qrCodes\": { \"read\": true, \"write\": false, \"delete\": false, \"assign\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n``` (partial update supported)"
},
"mcp_write_enabled": {
"type": "boolean",
"description": "Enable or disable MCP mutating operations for this key"
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the API key (false immediately revokes access)"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Update expiration timestamp (ISO 8601) or null to remove"
},
"ip_whitelist": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Update IP whitelist or null to remove restrictions"
},
"device_fingerprint": {
"type": [
"string",
"null"
],
"description": "Update device fingerprint or null to remove"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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"
}
}
},
"qrCodes": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"assign": {
"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",
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
],
"additionalProperties": false
}
📤 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
},
"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
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"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName"
]
},
"decider": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName"
]
}
}
}
},
"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"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName"
]
},
"decider": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName"
]
}
}
}
}
}
📤 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
Queue a password reset message for the 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": "Optional tenant ID for multi-tenant login. If not provided and user has multiple tenants, returns tenant list."
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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",
"displayName",
"fullName",
"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"
},
"fullName": {
"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",
"fullName",
"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"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"tenantName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"tenantId",
"tenantName"
],
"additionalProperties": false
},
"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 server-side callback completion in the platform auth broker"
},
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
}
},
"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",
"description": "Whether the created account must complete email verification before it can be used."
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"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/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
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
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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",
"displayName",
"fullName",
"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"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantLinks": {
"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
},
"description": "All tenant memberships linked to this user account"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"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: ใจดี)"
},
"displayName": {
"type": "string",
"description": "Public display name. Never null; falls back to generated fullName."
},
"fullName": {
"type": "string",
"description": "Generated full name using tenant-specific name ordering."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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"
},
"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",
"tenantId",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"created_at",
"updated_at",
"tenantName",
"groups",
"groupDetails",
"permissions",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
}
},
"required": [
"user"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantLinks": {
"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
},
"description": "All tenant memberships linked to this user account"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"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: ใจดี)"
},
"displayName": {
"type": "string",
"description": "Public display name. Never null; falls back to generated fullName."
},
"fullName": {
"type": "string",
"description": "Generated full name using tenant-specific name ordering."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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"
},
"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",
"tenantId",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"created_at",
"updated_at",
"tenantName",
"groups",
"groupDetails",
"permissions",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
}
},
"required": [
"user"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
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"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantLinks": {
"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
},
"description": "All tenant memberships linked to this user account"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"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: ใจดี)"
},
"displayName": {
"type": "string",
"description": "Public display name. Never null; falls back to generated fullName."
},
"fullName": {
"type": "string",
"description": "Generated full name using tenant-specific name ordering."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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"
},
"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",
"tenantId",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"settings",
"locale",
"emailConfirmedAt",
"emailVerificationStatus",
"created_at",
"updated_at",
"tenantName",
"groups",
"groupDetails",
"permissions",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
}
},
"required": [
"user"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
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 resolved direct-render 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"
],
"description": "Currently active avatar source"
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Resolved avatar URL ready for direct rendering; may be a signed media URL or remote provider URL"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID when the active source is remote"
}
},
"required": [
"source"
],
"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
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 ready for direct rendering; may be a signed media URL or remote provider 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"
}
]
}
},
"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"
}
]
}
},
"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.
📤 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"
}
]
}
},
"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"
},
"linkedResourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedSpaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"linkedUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"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"
},
"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"
}
]
}
},
"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
Dispatch due reminders through the canonical notification platform
Publish due reminders for a calendar through the unified notification inbox and advance each dispatched reminder to its next trigger time.
📥 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}/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
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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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",
"scopeType",
"scopeId",
"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
},
"scopeType": {
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
"scopeId": {
"type": "string",
"format": "uuid"
}
},
"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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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",
"scopeType",
"scopeId",
"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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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",
"scopeType",
"scopeId",
"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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"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"
},
"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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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",
"scopeType",
"scopeId",
"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
},
"scopeType": {
"anyOf": [
{
"type": "string",
"enum": [
"resource",
"space",
"user"
]
},
{
"type": "null"
}
]
},
"scopeId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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",
"scopeType",
"scopeId",
"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"
},
"mode": {
"type": "string",
"enum": [
"occupied_ranges",
"free_slots"
]
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
},
"resolvedTargets": {
"type": "object",
"properties": {
"calendarIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"resourceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"spaceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"required": [
"calendarIds",
"resourceIds",
"spaceIds"
],
"additionalProperties": false
},
"policy": {
"type": "object",
"properties": {
"maxWindowMinutes": {
"type": "integer",
"minimum": 1
},
"maxTargetIds": {
"type": "integer",
"minimum": 1
},
"blackoutRangeCount": {
"type": "integer",
"minimum": 0
}
},
"required": [
"maxWindowMinutes",
"maxTargetIds",
"blackoutRangeCount"
],
"additionalProperties": false
},
"intervals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"classification": {
"type": "string",
"enum": [
"occupied",
"blocked",
"free"
]
},
"status": {
"anyOf": [
{
"type": "string",
"enum": [
"draft",
"tentative",
"confirmed",
"cancelled",
"completed"
]
},
{
"type": "null"
}
]
},
"isAllDay": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
}
},
"required": [
"calendarId",
"startsAt",
"endsAt",
"classification",
"status",
"isAllDay"
],
"additionalProperties": false
}
}
},
"required": [
"windowStartsAt",
"windowEndsAt",
"mode",
"slotDurationMinutes",
"resolvedTargets",
"policy",
"intervals"
],
"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, and operational context.
📤 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"
}
]
}
},
"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}/availability-exceptions
List calendar availability exceptions
List one-off availability or blackout exceptions for a calendar.
📤 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"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"startsAt",
"endsAt",
"slotDurationMinutes",
"note",
"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/admin/calendars/{calendarId}/availability-exceptions
Create calendar availability exception
Create a one-off availability or blackout exception for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"slotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"note": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"availabilityKind",
"startsAt",
"endsAt"
],
"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"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"startsAt",
"endsAt",
"slotDurationMinutes",
"note",
"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/admin/calendars/{calendarId}/availability-exceptions/{exceptionId}
Delete calendar availability exception
Soft-delete a one-off availability exception for a calendar.
📤 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
PATCH
/api/v1/secure/admin/calendars/{calendarId}/availability-exceptions/{exceptionId}
Update calendar availability exception
Update a one-off availability or blackout exception for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 720
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"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"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"startsAt",
"endsAt",
"slotDurationMinutes",
"note",
"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/admin/calendars/{calendarId}/availability-rules
List calendar availability rules
List recurring weekly availability rules for a calendar.
📤 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"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"weekday": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"startMinuteOfDay": {
"type": "integer",
"minimum": 0,
"maximum": 1439
},
"endMinuteOfDay": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"validFrom": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"validUntil": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"weekday",
"startMinuteOfDay",
"endMinuteOfDay",
"validFrom",
"validUntil",
"slotDurationMinutes",
"note",
"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/admin/calendars/{calendarId}/availability-rules
Create calendar availability rule
Create a recurring weekly availability or blackout rule for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"weekday": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"startMinuteOfDay": {
"type": "integer",
"minimum": 0,
"maximum": 1439
},
"endMinuteOfDay": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"validFrom": {
"type": "string",
"format": "date"
},
"validUntil": {
"type": "string",
"format": "date"
},
"slotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"note": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"availabilityKind",
"weekday",
"startMinuteOfDay",
"endMinuteOfDay"
],
"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"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"weekday": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"startMinuteOfDay": {
"type": "integer",
"minimum": 0,
"maximum": 1439
},
"endMinuteOfDay": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"validFrom": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"validUntil": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"weekday",
"startMinuteOfDay",
"endMinuteOfDay",
"validFrom",
"validUntil",
"slotDurationMinutes",
"note",
"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/admin/calendars/{calendarId}/availability-rules/{ruleId}
Delete calendar availability rule
Soft-delete a recurring weekly availability rule for a calendar.
📤 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
PATCH
/api/v1/secure/admin/calendars/{calendarId}/availability-rules/{ruleId}
Update calendar availability rule
Update a recurring weekly availability or blackout rule for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"weekday": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"startMinuteOfDay": {
"type": "integer",
"minimum": 0,
"maximum": 1439
},
"endMinuteOfDay": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"validFrom": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"validUntil": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 720
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"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"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"availabilityKind": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"weekday": {
"type": "integer",
"minimum": 0,
"maximum": 6
},
"startMinuteOfDay": {
"type": "integer",
"minimum": 0,
"maximum": 1439
},
"endMinuteOfDay": {
"type": "integer",
"minimum": 1,
"maximum": 1440
},
"validFrom": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"validUntil": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"slotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"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",
"availabilityKind",
"weekday",
"startMinuteOfDay",
"endMinuteOfDay",
"validFrom",
"validUntil",
"slotDurationMinutes",
"note",
"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/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
GET
/api/v1/secure/admin/calendars/{calendarId}/scheduling-policy
Get calendar scheduling policy
Retrieve the persisted scheduling policy for a calendar.
📤 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"
},
"strategy": {
"type": "string",
"enum": [
"open_by_default",
"closed_by_default"
]
},
"defaultSlotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"minNoticeMinutes": {
"type": "integer",
"minimum": 0
},
"bookingHorizonDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"maxWindowMinutes": {
"type": "integer",
"minimum": 1
},
"maxTargetIds": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"allowWaitlist": {
"type": "boolean"
},
"requiresApproval": {
"type": "boolean"
},
"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",
"strategy",
"defaultSlotDurationMinutes",
"minNoticeMinutes",
"bookingHorizonDays",
"maxWindowMinutes",
"maxTargetIds",
"allowWaitlist",
"requiresApproval",
"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/admin/calendars/{calendarId}/scheduling-policy
Update calendar scheduling policy
Update the persisted scheduling policy that drives free-busy and booking behavior for a calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"strategy": {
"type": "string",
"enum": [
"open_by_default",
"closed_by_default"
]
},
"defaultSlotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"minNoticeMinutes": {
"type": "integer",
"minimum": 0,
"maximum": 525600
},
"bookingHorizonDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"maxWindowMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 525600
},
"maxTargetIds": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"allowWaitlist": {
"type": "boolean"
},
"requiresApproval": {
"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"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"strategy": {
"type": "string",
"enum": [
"open_by_default",
"closed_by_default"
]
},
"defaultSlotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"minNoticeMinutes": {
"type": "integer",
"minimum": 0
},
"bookingHorizonDays": {
"type": "integer",
"minimum": 1,
"maximum": 366
},
"maxWindowMinutes": {
"type": "integer",
"minimum": 1
},
"maxTargetIds": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"allowWaitlist": {
"type": "boolean"
},
"requiresApproval": {
"type": "boolean"
},
"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",
"strategy",
"defaultSlotDurationMinutes",
"minNoticeMinutes",
"bookingHorizonDays",
"maxWindowMinutes",
"maxTargetIds",
"allowWaitlist",
"requiresApproval",
"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
Calendar Booking
GET
/api/v1/secure/calendar/booking-requests
List booking requests
List booking requests for the current user or, when permitted, for a managed calendar.
📤 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"
},
"requestedByUserId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"pending",
"approved",
"denied",
"cancelled",
"waitlisted"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requestedStartsAt": {
"type": "string",
"format": "date-time"
},
"requestedEndsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"requestedSlotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"waitlistPosition": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"decisionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ownerNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"bookingReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chatReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resultingCalendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deniedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deniedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"cancelledByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"cancelledAt": {
"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",
"requestedByUserId",
"state",
"title",
"description",
"requestedStartsAt",
"requestedEndsAt",
"timezone",
"requestedSlotDurationMinutes",
"waitlistPosition",
"decisionReason",
"ownerNotes",
"bookingReferenceId",
"chatReferenceId",
"resultingCalendarEntryId",
"approvedByUserId",
"approvedAt",
"deniedByUserId",
"deniedAt",
"cancelledByUserId",
"cancelledAt",
"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/booking-requests
Create booking request
Create a booking request for a calendar window and optionally join the waitlist when allowed.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 4000
},
"startsAt": {
"type": "string",
"format": "date-time"
},
"endsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"requestedSlotDurationMinutes": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"allowWaitlist": {
"type": "boolean"
},
"bookingReferenceId": {
"type": "string",
"maxLength": 128
},
"chatReferenceId": {
"type": "string",
"maxLength": 128
}
},
"required": [
"calendarId",
"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"
},
"requestedByUserId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"pending",
"approved",
"denied",
"cancelled",
"waitlisted"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requestedStartsAt": {
"type": "string",
"format": "date-time"
},
"requestedEndsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"requestedSlotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"waitlistPosition": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"decisionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ownerNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"bookingReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chatReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resultingCalendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deniedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deniedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"cancelledByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"cancelledAt": {
"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",
"requestedByUserId",
"state",
"title",
"description",
"requestedStartsAt",
"requestedEndsAt",
"timezone",
"requestedSlotDurationMinutes",
"waitlistPosition",
"decisionReason",
"ownerNotes",
"bookingReferenceId",
"chatReferenceId",
"resultingCalendarEntryId",
"approvedByUserId",
"approvedAt",
"deniedByUserId",
"deniedAt",
"cancelledByUserId",
"cancelledAt",
"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/booking-requests/{id}/approve
Approve booking request
Approve a pending or waitlisted booking request and create the resulting calendar booking entry.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"ownerNotes": {
"type": "string",
"maxLength": 4000
}
},
"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"
},
"requestedByUserId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"pending",
"approved",
"denied",
"cancelled",
"waitlisted"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requestedStartsAt": {
"type": "string",
"format": "date-time"
},
"requestedEndsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"requestedSlotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"waitlistPosition": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"decisionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ownerNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"bookingReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chatReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resultingCalendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deniedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deniedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"cancelledByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"cancelledAt": {
"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",
"requestedByUserId",
"state",
"title",
"description",
"requestedStartsAt",
"requestedEndsAt",
"timezone",
"requestedSlotDurationMinutes",
"waitlistPosition",
"decisionReason",
"ownerNotes",
"bookingReferenceId",
"chatReferenceId",
"resultingCalendarEntryId",
"approvedByUserId",
"approvedAt",
"deniedByUserId",
"deniedAt",
"cancelledByUserId",
"cancelledAt",
"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/booking-requests/{id}/cancel
Cancel booking request
Cancel a booking request and cancel the resulting booking entry when the request was already approved.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"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"
},
"requestedByUserId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"pending",
"approved",
"denied",
"cancelled",
"waitlisted"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requestedStartsAt": {
"type": "string",
"format": "date-time"
},
"requestedEndsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"requestedSlotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"waitlistPosition": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"decisionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ownerNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"bookingReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chatReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resultingCalendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deniedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deniedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"cancelledByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"cancelledAt": {
"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",
"requestedByUserId",
"state",
"title",
"description",
"requestedStartsAt",
"requestedEndsAt",
"timezone",
"requestedSlotDurationMinutes",
"waitlistPosition",
"decisionReason",
"ownerNotes",
"bookingReferenceId",
"chatReferenceId",
"resultingCalendarEntryId",
"approvedByUserId",
"approvedAt",
"deniedByUserId",
"deniedAt",
"cancelledByUserId",
"cancelledAt",
"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/booking-requests/{id}/deny
Deny booking request
Deny a booking request with a required reason and optional owner notes.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"ownerNotes": {
"type": "string",
"maxLength": 4000
}
},
"required": [
"reason"
],
"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"
},
"requestedByUserId": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"pending",
"approved",
"denied",
"cancelled",
"waitlisted"
]
},
"title": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requestedStartsAt": {
"type": "string",
"format": "date-time"
},
"requestedEndsAt": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"requestedSlotDurationMinutes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"waitlistPosition": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"decisionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ownerNotes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"bookingReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"chatReferenceId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resultingCalendarEntryId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"approvedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deniedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"deniedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"cancelledByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"cancelledAt": {
"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",
"requestedByUserId",
"state",
"title",
"description",
"requestedStartsAt",
"requestedEndsAt",
"timezone",
"requestedSlotDurationMinutes",
"waitlistPosition",
"decisionReason",
"ownerNotes",
"bookingReferenceId",
"chatReferenceId",
"resultingCalendarEntryId",
"approvedByUserId",
"approvedAt",
"deniedByUserId",
"deniedAt",
"cancelledByUserId",
"cancelledAt",
"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
Calendar Groups
GET
/api/v1/secure/calendar-groups/
List calendar groups
List calendar groups for the tenant. Groups define a broadcast source calendar whose entries are virtually merged into all member calendars.
📤 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"
}
]
},
"sourceCalendarId": {
"type": "string",
"format": "uuid"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"memberCount": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"name",
"sourceCalendarId",
"ownerUserId",
"metadata",
"memberCount",
"createdAt",
"updatedAt",
"createdBy"
],
"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-groups/
Create calendar group
Create a calendar group. The sourceCalendarId is the broadcast calendar whose entries will be merged into all member calendars at query time.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"sourceCalendarId": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"name",
"sourceCalendarId"
],
"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"
}
]
},
"sourceCalendarId": {
"type": "string",
"format": "uuid"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"memberCount": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"name",
"sourceCalendarId",
"ownerUserId",
"metadata",
"memberCount",
"createdAt",
"updatedAt",
"createdBy"
],
"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-groups/{id}
Delete calendar group
📤 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-groups/{id}
Get calendar group
📤 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"
}
]
},
"sourceCalendarId": {
"type": "string",
"format": "uuid"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"memberCount": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"name",
"sourceCalendarId",
"ownerUserId",
"metadata",
"memberCount",
"createdAt",
"updatedAt",
"createdBy"
],
"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-groups/{id}
Update calendar group
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string"
},
"metadata": {
"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"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sourceCalendarId": {
"type": "string",
"format": "uuid"
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"memberCount": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"name",
"sourceCalendarId",
"ownerUserId",
"metadata",
"memberCount",
"createdAt",
"updatedAt",
"createdBy"
],
"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-groups/{id}/members
List calendar group members
List all member calendars in a group.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"groupId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarName": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sortOrder": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"groupId",
"calendarId",
"calendarName",
"label",
"sortOrder",
"createdAt"
],
"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-groups/{id}/members
Add calendar to group
Add a calendar as a member of this group. Its window and free/busy results will automatically include all entries from the group source calendar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"calendarId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string",
"maxLength": 255
},
"sortOrder": {
"type": "integer",
"minimum": 0
}
},
"required": [
"calendarId"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"groupId": {
"type": "string",
"format": "uuid"
},
"calendarId": {
"type": "string",
"format": "uuid"
},
"calendarName": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sortOrder": {
"type": "integer"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"groupId",
"calendarId",
"calendarName",
"label",
"sortOrder",
"createdAt"
],
"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-groups/{id}/members/{memberId}
Remove calendar from group
📤 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
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"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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",
"filter_id",
"level",
"sort_order",
"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
},
"sort_order": {
"type": "number",
"minimum": 0,
"description": "Manual sibling sort order override"
},
"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)"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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"
}
]
}
}
},
"description": "Translations for additional languages only (excludes the base language)"
},
"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",
"filter_id",
"level",
"sort_order",
"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 204
Category 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/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)"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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"
}
]
}
}
},
"description": "Translations for additional languages only (excludes the base language)"
},
"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",
"filter_id",
"level",
"sort_order",
"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
},
"sort_order": {
"type": "number",
"minimum": 0,
"description": "Manual sibling sort order override"
},
"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)"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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"
}
]
}
}
},
"description": "Translations for additional languages only (excludes the base language)"
},
"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",
"filter_id",
"level",
"sort_order",
"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"
},
"categoryId": {
"type": "string",
"format": "uuid"
},
"entityType": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"categoryId",
"entityType",
"entityId",
"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": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"categoryId": {
"type": "string",
"format": "uuid"
},
"locale": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenantId",
"categoryId",
"locale",
"name",
"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"
},
"categoryId": {
"type": "string",
"format": "uuid"
},
"entityType": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"categoryId",
"entityType",
"entityId",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/{id}/sort-order/move
Move category sort order
Move a category up or down within its sibling list
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"direction"
],
"properties": {
"direction": {
"type": "string",
"enum": [
"up",
"down"
]
}
}
}
📤 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)"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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"
}
]
}
}
},
"description": "Translations for additional languages only (excludes the base language)"
},
"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",
"filter_id",
"level",
"sort_order",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_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"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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",
"filter_id",
"level",
"sort_order",
"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
POST
/api/v1/secure/taxonomy/categories/sort-order/reset
Reset category sort order
Reset category sibling ordering by name or creation date
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"strategy"
],
"properties": {
"strategy": {
"type": "string",
"enum": [
"name",
"created_at"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"updated_count": {
"type": "number"
},
"strategy": {
"type": "string",
"enum": [
"name",
"created_at"
]
}
},
"required": [
"updated_count",
"strategy"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
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"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
},
"description": "Translations for additional languages only (excludes the base language)"
},
"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",
"filter_id",
"level",
"sort_order",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
Chat
POST
/api/v1/secure/chat/actors/conversations
Create or return an actor-owned chat conversation
Create a durable resource-owned or space-owned conversation for a customer-facing user, optionally posting an opening message. Non-owner users can start the actor thread for themselves, and eligible owners can start the same actor thread toward any non-owner tenant user.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ownerActor"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"resource",
"space"
]
},
"resourceId": {
"type": "string",
"format": "uuid"
},
"spaceId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"type": {
"enum": [
"resource"
]
}
}
},
"then": {
"required": [
"resourceId"
]
}
},
{
"if": {
"properties": {
"type": {
"enum": [
"space"
]
}
}
},
"then": {
"required": [
"spaceId"
]
}
}
]
},
"participantUserId": {
"type": "string",
"format": "uuid"
},
"initialMessage": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"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/chat/bootstrap
Get chat bootstrap payload
Return unread totals, bounded conversation summaries, online-state policy, and realtime bootstrap data.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"unreadTotal",
"conversations",
"onlineStatePolicy",
"realtime"
],
"properties": {
"unreadTotal": {
"type": "integer",
"minimum": 0
},
"conversations": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"additionalProperties": false
},
"maxItems": 20
},
"onlineStatePolicy": {
"type": "object",
"required": [
"approximate",
"source",
"states",
"recentlyActiveWindowSeconds",
"refreshTriggers",
"maxTrackedParticipants"
],
"properties": {
"approximate": {
"type": "boolean",
"enum": [
true
]
},
"source": {
"type": "string",
"description": "Greenfield presence source contract. The backend derives roster presence from Centrifugo presence_stats on dedicated presence-only channels.",
"enum": [
"centrifugo_presence_channel"
]
},
"states": {
"type": "array",
"description": "Canonical presence states supported by the current backend contract.",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
}
},
"recentlyActiveWindowSeconds": {
"type": "integer",
"description": "A user is recently_active when they were observed online within the last 15 seconds but are not currently present.",
"enum": [
15
]
},
"refreshTriggers": {
"type": "array",
"description": "Client events that may trigger one bounded GET /api/v1/secure/chat/online-state roster snapshot. These are event triggers, not a polling cadence.",
"minItems": 5,
"maxItems": 5,
"items": {
"type": "string",
"enum": [
"bootstrap",
"reconnect",
"online_state_join",
"online_state_leave",
"conversation_visibility_change"
]
}
},
"maxTrackedParticipants": {
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"additionalProperties": false
},
"realtime": {
"type": "object",
"required": [
"token",
"expiresAt",
"transport",
"personalChannel",
"presenceChannel"
],
"properties": {
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"personalChannel": {
"type": "string"
},
"presenceChannel": {
"type": "string",
"description": "Current user presence-only Centrifugo channel. Clients subscribe to this channel so peers can resolve online-state through event-driven roster updates without granting inbox access."
},
"refreshRequired": {
"type": "boolean"
},
"transport": {
"type": "object",
"required": [
"wsEndpoint",
"useTls"
],
"properties": {
"wsEndpoint": {
"type": "string"
},
"useTls": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"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/secure/chat/conversations
List chat conversations
Return the authenticated user's inbox-style conversation list with cursor pagination.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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
Create or return a direct chat conversation
Canonicalize a direct participant pair, return the existing conversation when present, or create a new durable direct conversation with an optional opening message.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"participantUserId"
],
"properties": {
"participantUserId": {
"type": "string",
"format": "uuid"
},
"initialMessage": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"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/chat/conversations/{conversationId}
Get a chat conversation summary
Return the durable summary metadata for one conversation visible to the authenticated user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"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/chat/conversations/{conversationId}/assignment
Update actor-owned chat assignment state
Accept, assign, take over, or reassign responsibility for an actor-owned chat conversation while preserving shared-owner visibility.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"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/chat/conversations/{conversationId}/messages
List chat messages
Return a bounded durable message timeline for one visible conversation with latest-page cursor pagination and forward delta sync.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"conversationId",
"senderUserId",
"content",
"mediaAttachments",
"sentAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationId": {
"type": "string",
"format": "uuid"
},
"senderUserId": {
"type": "string",
"format": "uuid"
},
"clientMessageId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content": {
"type": "string"
},
"mediaAttachments": {
"description": "Backend-enriched attachment metadata for the message. Use only this block for previews and downloads instead of inferring storage paths or thumbnail variants in the client.",
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"mediaFileId",
"mimeType",
"fileSizeBytes",
"publicUrl",
"thumbnailUrls"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"mimeType": {
"type": "string"
},
"fileSizeBytes": {
"type": "integer",
"minimum": 0
},
"originalFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"publicUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Signed download URL for the original media file when available. Use this only for explicit open/download actions, not normal image-message rendering."
},
"thumbnailUrls": {
"description": "Normalized optimized image preview URLs for conversation rendering. When present, only the canonical small, medium, large, and preview keys may appear; non-canonical media metadata variants are filtered out. Null means no canonical preview thumbnails are available for the attachment.",
"anyOf": [
{
"type": "object",
"properties": {
"small": {
"type": "string",
"description": "Signed URL for the small image thumbnail variant."
},
"medium": {
"type": "string",
"description": "Signed URL for the medium image thumbnail variant."
},
"large": {
"type": "string",
"description": "Signed URL for the large image thumbnail variant."
},
"preview": {
"type": "string",
"description": "Signed URL for the preview image thumbnail variant."
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"sentAt": {
"type": "string",
"format": "date-time"
},
"deliveredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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/{conversationId}/messages
Send chat message
Create a durable chat message for one visible conversation and update the bounded unread state.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"clientMessageId": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"content": {
"type": "string",
"maxLength": 4000
},
"mediaAttachments": {
"description": "Optional uploaded media references for attachment-only or mixed chat messages. Upload each file first through POST /api/v1/services/media/upload and send the returned mediaFileId values here.",
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"required": [
"mediaFileId"
],
"properties": {
"mediaFileId": {
"type": "string",
"format": "uuid",
"description": "Canonical id of an already uploaded PVE media file to attach to the message."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false,
"required": [
"clientMessageId"
],
"anyOf": [
{
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"minLength": 1
}
}
},
{
"type": "object",
"required": [
"mediaAttachments"
],
"properties": {
"mediaAttachments": {
"type": "array",
"minItems": 1
}
}
}
]
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationId",
"senderUserId",
"content",
"mediaAttachments",
"sentAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationId": {
"type": "string",
"format": "uuid"
},
"senderUserId": {
"type": "string",
"format": "uuid"
},
"clientMessageId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content": {
"type": "string"
},
"mediaAttachments": {
"description": "Backend-enriched attachment metadata for the message. Use only this block for previews and downloads instead of inferring storage paths or thumbnail variants in the client.",
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"mediaFileId",
"mimeType",
"fileSizeBytes",
"publicUrl",
"thumbnailUrls"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"mimeType": {
"type": "string"
},
"fileSizeBytes": {
"type": "integer",
"minimum": 0
},
"originalFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"publicUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Signed download URL for the original media file when available. Use this only for explicit open/download actions, not normal image-message rendering."
},
"thumbnailUrls": {
"description": "Normalized optimized image preview URLs for conversation rendering. When present, only the canonical small, medium, large, and preview keys may appear; non-canonical media metadata variants are filtered out. Null means no canonical preview thumbnails are available for the attachment.",
"anyOf": [
{
"type": "object",
"properties": {
"small": {
"type": "string",
"description": "Signed URL for the small image thumbnail variant."
},
"medium": {
"type": "string",
"description": "Signed URL for the medium image thumbnail variant."
},
"large": {
"type": "string",
"description": "Signed URL for the large image thumbnail variant."
},
"preview": {
"type": "string",
"description": "Signed URL for the preview image thumbnail variant."
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"sentAt": {
"type": "string",
"format": "date-time"
},
"deliveredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deletedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/chat/conversations/{conversationId}/read-state
Update chat read state
Update the durable read cursor for one visible conversation.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"lastSeenMessageId": {
"type": "string",
"format": "uuid"
},
"readCursorAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"required": [
"lastSeenMessageId"
]
},
{
"type": "object",
"required": [
"readCursorAt"
]
}
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"conversationType",
"peer",
"unreadCount",
"lastMessageAt",
"lastReadAt",
"actorContext",
"participants"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationType": {
"type": "string",
"enum": [
"direct",
"resource",
"space",
"group"
]
},
"peer": {
"type": "object",
"required": [
"type",
"displayName",
"fullName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
],
"additionalProperties": false
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastMessagePreview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastMessageSenderUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"actorContext": {
"anyOf": [
{
"type": "object",
"required": [
"ownerActor",
"initiatingUserId",
"sharedOwnerVisibility",
"assignment"
],
"properties": {
"ownerActor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
"initiatingUserId": {
"type": "string",
"format": "uuid"
},
"sharedOwnerVisibility": {
"type": "string",
"enum": [
"shared_owners",
"assigned_owner_only"
]
},
"assignment": {
"type": "object",
"required": [
"state"
],
"properties": {
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"assigned",
"reassigned"
]
},
"assignedOwnerUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"acceptedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"assignmentUpdatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastTakenOverByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastTakenOverAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastReassignedByUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastReassignedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"participants": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"role",
"state",
"displayName",
"fullName"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"participant",
"customer",
"owner",
"assignee",
"watcher"
]
},
"state": {
"type": "string",
"enum": [
"invited",
"pending",
"accepted",
"active",
"archived"
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"avatarUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"linkedActor": {
"anyOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space",
"group"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"groupId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"group"
]
}
},
"required": [
"groupId"
]
}
]
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"lastReadAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"onlineState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster snapshot for the user the client should currently surface for this conversation. Direct chats target the peer user. Actor-owned customer views target the assigned owner when present, otherwise another visible owner-side participant. Actor-owned owner or assignee views target the customer. Update this from bootstrap and event-triggered online-state snapshots, not polling."
}
},
"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/chat/lookup/actor-codes
Issue or reuse a chat actor short code
Return the tenant-scoped short code for a visible user, resource, or space actor so apps can share a compact identifier instead of raw UUIDs.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"actor"
],
"properties": {
"actor": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"code",
"actor"
],
"properties": {
"code": {
"type": "string"
},
"actor": {
"type": "object",
"required": [
"type",
"displayName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
}
]
}
},
"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/chat/lookup/actor-codes/resolve
Resolve a chat actor short code
Resolve a tenant-scoped short code back to the canonical actor identity and display label for chat initiation.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"minLength": 6,
"maxLength": 16,
"pattern": "^[A-HJ-NP-Z2-9]+$"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"code",
"actor"
],
"properties": {
"code": {
"type": "string"
},
"actor": {
"type": "object",
"required": [
"type",
"displayName"
],
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
]
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
}
},
"additionalProperties": false,
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"enum": [
"user"
]
}
},
"required": [
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"resource"
]
}
},
"required": [
"resourceId"
]
},
{
"type": "object",
"properties": {
"type": {
"enum": [
"space"
]
}
},
"required": [
"spaceId"
]
}
]
}
},
"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/chat/online-state
Get chat online state
Return approximate online-state snapshots for the users the client should currently surface. Direct chats resolve the peer user. Actor-owned customer views resolve the assigned owner when present, otherwise another visible owner-side participant; owner-side views resolve the customer.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"userId",
"state",
"observedAt"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid",
"description": "The concrete user whose approximate online state was resolved. This may be a direct peer, an assigned owner, another visible owner-side participant, or the customer depending on conversation context."
},
"state": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
],
"description": "Approximate roster presence state derived from Centrifugo presence-only channels, not a durable chat delivery guarantee. Clients receive it from bootstrap or event-triggered roster snapshots only."
},
"observedAt": {
"type": "string",
"format": "date-time",
"description": "Server timestamp for when the presence snapshot was observed."
}
},
"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/chat/presence/actors/self
List self-manageable chat presence actors
Return the authenticated user actor plus any resource or space actors they may administer for chat presence self-service. Manual presence changes are allowed by default; tenant admins can restrict specific actors, which returns manualOverrideAllowed=false.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.",
"required": [
"actor",
"automaticState",
"effectiveState",
"effectiveSource",
"manualOverrideAllowed",
"manualState",
"observedAt"
],
"properties": {
"actor": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"userId",
"label"
],
"properties": {
"type": {
"enum": [
"user"
]
},
"userId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"resourceId",
"label"
],
"properties": {
"type": {
"enum": [
"resource"
]
},
"resourceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"spaceId",
"label"
],
"properties": {
"type": {
"enum": [
"space"
]
},
"spaceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"automaticState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveSource": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"manualOverrideAllowed": {
"type": "boolean"
},
"manualState": {
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/chat/presence/actors/self
Update self chat presence override
Set or clear the current manual chat presence state for the authenticated user actor or a resource/space actor the user administers. Manual changes are allowed by default unless a tenant admin restricted the specific actor; send manualState=null to return to automatic presence.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"actor",
"manualState"
],
"properties": {
"actor": {
"type": "object",
"description": "Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
],
"description": "Actor kind whose chat presence is being resolved or manually overridden."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=user."
},
"resourceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=resource. Use this for seller/resource presence in customer-facing chat."
},
"spaceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=space."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"type",
"userId"
]
},
{
"required": [
"type",
"resourceId"
]
},
{
"required": [
"type",
"spaceId"
]
}
]
},
"manualState": {
"description": "Manual state for the user actor or a resource/space actor the caller administers. Manual changes are allowed by default unless a tenant admin restricted this actor; use online on active chat page, recently_active on visibility loss if the app wants an away signal, or null to return to automatic presence.",
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.",
"required": [
"actor",
"automaticState",
"effectiveState",
"effectiveSource",
"manualOverrideAllowed",
"manualState",
"observedAt"
],
"properties": {
"actor": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"userId",
"label"
],
"properties": {
"type": {
"enum": [
"user"
]
},
"userId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"resourceId",
"label"
],
"properties": {
"type": {
"enum": [
"resource"
]
},
"resourceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"spaceId",
"label"
],
"properties": {
"type": {
"enum": [
"space"
]
},
"spaceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"automaticState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveSource": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"manualOverrideAllowed": {
"type": "boolean"
},
"manualState": {
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/chat/push/devices
Register chat push device
Create or refresh one backend-owned chat push device registration for the authenticated user. For webpush clients, pushToken must contain the serialized PushSubscription JSON. Reusing installationId updates the token and metadata instead of creating duplicate rows.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"installationId",
"platform",
"pushToken"
],
"properties": {
"installationId": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"platform": {
"type": "string",
"enum": [
"ios",
"android",
"web"
]
},
"pushToken": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"appVersion": {
"type": "string",
"maxLength": 50
},
"deviceName": {
"type": "string",
"maxLength": 255
},
"locale": {
"type": "string",
"maxLength": 20
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"deviceId",
"installationId",
"platform",
"pushTokenState",
"updatedAt"
],
"properties": {
"deviceId": {
"type": "string",
"format": "uuid"
},
"installationId": {
"type": "string"
},
"platform": {
"type": "string",
"enum": [
"ios",
"android",
"web"
]
},
"pushTokenState": {
"type": "string",
"enum": [
"active",
"invalid",
"retired"
]
},
"lastValidatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"updatedAt": {
"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
DELETE
/api/v1/secure/chat/push/devices/{deviceId}
Retire chat push device
Retire one backend-owned chat push device registration for the authenticated user.
📤 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/chat/push/focus-state
Clear active chat push focus state
Clear active conversation focus so same-conversation push suppression no longer applies to this user/session.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"active",
"conversationId",
"lastSeenAt",
"expiresAt"
],
"properties": {
"active": {
"type": "boolean"
},
"conversationId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastSeenAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PUT
/api/v1/secure/chat/push/focus-state
Set active chat push focus state
Heartbeat the currently active conversation focus used for same-conversation push suppression on this user/session. Clients should refresh before ttlSeconds expires while the thread is foregrounded.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"conversationId"
],
"properties": {
"conversationId": {
"type": "string",
"format": "uuid"
},
"ttlSeconds": {
"type": "integer",
"minimum": 15,
"maximum": 300,
"description": "Focus heartbeat TTL in seconds. Defaults to 45 seconds."
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"active",
"conversationId",
"lastSeenAt",
"expiresAt"
],
"properties": {
"active": {
"type": "boolean"
},
"conversationId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"lastSeenAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/chat/push/preferences
Update chat push preferences
Update backend-owned chat push preferences for the authenticated user.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"muteWhileActiveInThread": {
"type": "boolean"
},
"mutedConversationIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"enabled",
"muteWhileActiveInThread",
"mutedConversationIds"
],
"properties": {
"enabled": {
"type": "boolean"
},
"muteWhileActiveInThread": {
"type": "boolean"
},
"mutedConversationIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"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/chat/push/status
Get chat push status
Return backend-owned chat push readiness, registered devices, and current user preferences, including muteWhileActiveInThread and per-conversation mute state used by push fanout suppression.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"supported",
"devices",
"preferences"
],
"properties": {
"supported": {
"type": "boolean"
},
"devices": {
"type": "array",
"items": {
"type": "object",
"required": [
"deviceId",
"installationId",
"platform",
"pushTokenState",
"updatedAt"
],
"properties": {
"deviceId": {
"type": "string",
"format": "uuid"
},
"installationId": {
"type": "string"
},
"platform": {
"type": "string",
"enum": [
"ios",
"android",
"web"
]
},
"pushTokenState": {
"type": "string",
"enum": [
"active",
"invalid",
"retired"
]
},
"lastValidatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"preferences": {
"type": "object",
"required": [
"enabled",
"muteWhileActiveInThread",
"mutedConversationIds"
],
"properties": {
"enabled": {
"type": "boolean"
},
"muteWhileActiveInThread": {
"type": "boolean"
},
"mutedConversationIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"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
POST
/api/v1/secure/chat/realtime/session
Issue chat realtime session
Issue a Centrifugo connection token and transport configuration for the authenticated user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"token",
"expiresAt",
"transport",
"personalChannel",
"presenceChannel"
],
"properties": {
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"personalChannel": {
"type": "string"
},
"presenceChannel": {
"type": "string",
"description": "Current user presence-only Centrifugo channel. Clients subscribe to this channel so peers can resolve online-state through event-driven roster updates without granting inbox access."
},
"refreshRequired": {
"type": "boolean"
},
"transport": {
"type": "object",
"required": [
"wsEndpoint",
"useTls"
],
"properties": {
"wsEndpoint": {
"type": "string"
},
"useTls": {
"type": "boolean"
}
},
"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
POST
/api/v1/secure/chat/realtime/subscriptions
Issue chat realtime subscription grants
Issue scoped Centrifugo subscription tokens for authorized chat conversations and optional approximate online-state tracking. Online-state grants target presence-only channels for the concrete users implied by the visible conversation memberships.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"conversationIds"
],
"properties": {
"conversationIds": {
"description": "Visible conversation ids that need scoped Centrifugo subscription grants.",
"type": "array",
"maxItems": 50,
"items": {
"type": "string",
"format": "uuid"
}
},
"includeOnlineState": {
"type": "boolean",
"description": "Also issue online-state event grants for the tracked users implied by the requested visible roster. These grants are derived from visible conversation membership, not only direct-chat peer columns, so actor-owned chats cover assigned owners, shared owners, watchers, and customer participants as needed. Clients use these grants for event-driven state changes, not polling."
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"subscriptions",
"onlineStateSubscriptions"
],
"properties": {
"subscriptions": {
"description": "Per-conversation Centrifugo grants for the visible conversation set.",
"type": "array",
"items": {
"type": "object",
"required": [
"channel",
"token",
"expiresAt"
],
"properties": {
"channel": {
"type": "string"
},
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"conversationId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"onlineStateUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Null for normal conversation subscriptions. Present only when a grant also doubles as an online-state subscription target."
}
},
"additionalProperties": false
}
},
"onlineStateSubscriptions": {
"description": "Per-user Centrifugo grants for approximate online-state event tracking. Each grant subscribes to a presence-only channel for a visible roster user and never grants another user's personal inbox channel. Use these events to update roster state; do not poll.",
"type": "array",
"items": {
"type": "object",
"required": [
"channel",
"token",
"expiresAt"
],
"properties": {
"channel": {
"type": "string"
},
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"conversationId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"onlineStateUserId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "The concrete user whose presence-only channel this online-state grant tracks."
}
},
"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
Chat Admin
POST
/api/v1/secure/chat/admin/broadcast
Broadcast a tenant-wide admin notification
Publish one durable tenant-wide admin broadcast notification from the current tenant admin to every active user in the tenant.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"targetUserCount",
"conversationCount",
"deliveredMessageCount"
],
"properties": {
"targetUserCount": {
"type": "integer",
"minimum": 0
},
"conversationCount": {
"type": "integer",
"minimum": 0
},
"deliveredMessageCount": {
"type": "integer",
"minimum": 0
}
},
"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/chat/admin/configuration
Get tenant chat admin configuration
Return the tenant-scoped chat configuration that drives pagination, online-state policy, and retention defaults.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"pushEnabled",
"onlineStateEnabled",
"defaultConversationPageSize",
"defaultTimelinePageSize",
"messageRetentionDays",
"initiationPolicy"
],
"properties": {
"pushEnabled": {
"type": "boolean"
},
"onlineStateEnabled": {
"type": "boolean"
},
"defaultConversationPageSize": {
"type": "integer"
},
"defaultTimelinePageSize": {
"type": "integer"
},
"messageRetentionDays": {
"type": "integer"
},
"initiationPolicy": {
"type": "object",
"required": [
"direct",
"group"
],
"properties": {
"direct": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"group": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"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/secure/chat/admin/configuration
Update tenant chat admin configuration
Update tenant-scoped chat configuration values. Write access is limited to tenant admins and system admins.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"pushEnabled": {
"type": "boolean"
},
"onlineStateEnabled": {
"type": "boolean"
},
"defaultConversationPageSize": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"defaultTimelinePageSize": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"messageRetentionDays": {
"type": "integer",
"minimum": 1,
"maximum": 3650
},
"initiationPolicy": {
"type": "object",
"required": [
"direct",
"group"
],
"properties": {
"direct": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"group": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"pushEnabled",
"onlineStateEnabled",
"defaultConversationPageSize",
"defaultTimelinePageSize",
"messageRetentionDays",
"initiationPolicy"
],
"properties": {
"pushEnabled": {
"type": "boolean"
},
"onlineStateEnabled": {
"type": "boolean"
},
"defaultConversationPageSize": {
"type": "integer"
},
"defaultTimelinePageSize": {
"type": "integer"
},
"messageRetentionDays": {
"type": "integer"
},
"initiationPolicy": {
"type": "object",
"required": [
"direct",
"group"
],
"properties": {
"direct": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"group": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"resource": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"user",
"resource",
"space"
],
"properties": {
"user": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"resource": {
"type": "string",
"enum": [
"allow",
"deny"
]
},
"space": {
"type": "string",
"enum": [
"allow",
"deny"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"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/secure/chat/admin/diagnostic-summary
Get tenant chat diagnostic summary
Return the tenant-scoped diagnostic summary for push-device health and recent push-delivery outcomes. Read access is limited to tenant admins and system admins.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"pushEnabled",
"providerRoutingMode",
"activeDeviceCount",
"invalidDeviceCount",
"queuedDeliveryCount",
"suppressedDeliveryCount",
"failedDeliveryCount",
"lastQueuedDeliveryAt",
"lastFailedDeliveryAt"
],
"properties": {
"pushEnabled": {
"type": "boolean"
},
"providerRoutingMode": {
"type": "string",
"enum": [
"managed",
"disabled"
]
},
"activeDeviceCount": {
"type": "integer",
"minimum": 0
},
"invalidDeviceCount": {
"type": "integer",
"minimum": 0
},
"queuedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"suppressedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"failedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"lastQueuedDeliveryAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastFailedDeliveryAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/chat/admin/overview
Get tenant chat admin overview
Return the tenant-wide chat overview metrics used by the tenant admin overview page. Read access is limited to tenant admins and system admins.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"activeConversationCount",
"messagesLast24h",
"pushQueueDepth",
"pushFailureRate",
"activeConnections",
"messageRateLimit"
],
"properties": {
"activeConversationCount": {
"type": "integer",
"minimum": 0
},
"messagesLast24h": {
"type": "integer",
"minimum": 0
},
"pushQueueDepth": {
"type": "integer",
"minimum": 0
},
"pushFailureRate": {
"type": "number",
"minimum": 0
},
"activeConnections": {
"type": "integer",
"minimum": 0
},
"messageRateLimit": {
"type": "object",
"required": [
"activeSends",
"sendsInWindow",
"remainingInWindow",
"maxConcurrent",
"maxPerMinute",
"rateLimitedCount",
"utilizationPercent",
"lastMessageAt",
"lastRateLimitedAt"
],
"properties": {
"activeSends": {
"type": "integer",
"minimum": 0
},
"sendsInWindow": {
"type": "integer",
"minimum": 0
},
"remainingInWindow": {
"type": "integer",
"minimum": 0
},
"maxConcurrent": {
"type": "integer",
"minimum": 1
},
"maxPerMinute": {
"type": "integer",
"minimum": 1
},
"rateLimitedCount": {
"type": "integer",
"minimum": 0
},
"utilizationPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastRateLimitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"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/secure/chat/admin/presence/actors
Update tenant chat actor presence override
Restrict or allow self-service manual presence for a user, resource, or space actor and optionally set its current manual state. Tenant admins can set manualState even when self-service is restricted.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"actor"
],
"properties": {
"actor": {
"type": "object",
"description": "Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
],
"description": "Actor kind whose chat presence is being resolved or manually overridden."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=user."
},
"resourceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=resource. Use this for seller/resource presence in customer-facing chat."
},
"spaceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=space."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"type",
"userId"
]
},
{
"required": [
"type",
"resourceId"
]
},
{
"required": [
"type",
"spaceId"
]
}
]
},
"manualOverrideAllowed": {
"type": "boolean",
"description": "Allows or restricts self-service manual presence for the actor. Default policy allows manual changes unless this actor is explicitly restricted."
},
"manualState": {
"description": "Manual effective state to apply as a tenant admin. Use null to clear the manual state and return to automatic presence. Tenant admins may set this even when self-service is restricted.",
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.",
"required": [
"actor",
"automaticState",
"effectiveState",
"effectiveSource",
"manualOverrideAllowed",
"manualState",
"observedAt"
],
"properties": {
"actor": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"userId",
"label"
],
"properties": {
"type": {
"enum": [
"user"
]
},
"userId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"resourceId",
"label"
],
"properties": {
"type": {
"enum": [
"resource"
]
},
"resourceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"spaceId",
"label"
],
"properties": {
"type": {
"enum": [
"space"
]
},
"spaceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"automaticState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveSource": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"manualOverrideAllowed": {
"type": "boolean"
},
"manualState": {
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/chat/admin/presence/roster
Resolve tenant chat presence roster
Return automatic and effective chat presence state for a selected roster of user, resource, and space actors.
📥 REQUEST BODY
Inline Schema
Tenant-admin roster presence resolution request. Clients submit bounded actor targets and render the returned automatic/effective presence states as roster attributes. This is not a polling contract.
{
"type": "object",
"description": "Tenant-admin roster presence resolution request. Clients submit bounded actor targets and render the returned automatic/effective presence states as roster attributes. This is not a polling contract.",
"required": [
"actors"
],
"properties": {
"actors": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"description": "Presence actor target. Send exactly one id field matching type: userId for user, resourceId for resource, or spaceId for space.",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"resource",
"space"
],
"description": "Actor kind whose chat presence is being resolved or manually overridden."
},
"userId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=user."
},
"resourceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=resource. Use this for seller/resource presence in customer-facing chat."
},
"spaceId": {
"type": "string",
"format": "uuid",
"description": "Required only when type=space."
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"type",
"userId"
]
},
{
"required": [
"type",
"resourceId"
]
},
{
"required": [
"type",
"spaceId"
]
}
]
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Resolved roster presence state for a user, resource, or space actor. Render effectiveState as the roster indicator, preserve automaticState for diagnostics/secondary UI, and do not derive actor presence from client polling timers.",
"required": [
"actor",
"automaticState",
"effectiveState",
"effectiveSource",
"manualOverrideAllowed",
"manualState",
"observedAt"
],
"properties": {
"actor": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"userId",
"label"
],
"properties": {
"type": {
"enum": [
"user"
]
},
"userId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"resourceId",
"label"
],
"properties": {
"type": {
"enum": [
"resource"
]
},
"resourceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"spaceId",
"label"
],
"properties": {
"type": {
"enum": [
"space"
]
},
"spaceId": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"automaticState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveState": {
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
"effectiveSource": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"manualOverrideAllowed": {
"type": "boolean"
},
"manualState": {
"anyOf": [
{
"type": "string",
"enum": [
"online",
"recently_active",
"offline"
]
},
{
"type": "null"
}
]
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/chat/admin/push-configuration
Get tenant chat push configuration
Return tenant-scoped chat push policy including provider routing mode, default TTL, suppressPushWhenActiveInConversation, quietHoursSupported capability flag, fanout mode, and appOrigin used to build absolute webpush deeplinks.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"providerRoutingMode",
"pushEnabled",
"defaultTtlSeconds",
"quietHoursSupported",
"suppressPushWhenActiveInConversation",
"pushFanoutMode",
"appOrigin"
],
"properties": {
"providerRoutingMode": {
"type": "string",
"enum": [
"managed",
"disabled"
]
},
"pushEnabled": {
"type": "boolean"
},
"defaultTtlSeconds": {
"type": "integer",
"minimum": 0,
"maximum": 259200
},
"quietHoursSupported": {
"type": "boolean"
},
"suppressPushWhenActiveInConversation": {
"type": "boolean"
},
"pushFanoutMode": {
"type": "string",
"enum": [
"all_active_devices"
]
},
"appOrigin": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"
},
{
"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
PATCH
/api/v1/secure/chat/admin/push-configuration
Update tenant chat push configuration
Update tenant-scoped chat push delivery policy values. quietHoursSupported is a capability flag for clients; no tenant quiet-hours schedule is enforced by this endpoint yet. appOrigin must be an absolute origin and is used for push click-through URL generation.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"providerRoutingMode": {
"type": "string",
"enum": [
"managed",
"disabled"
]
},
"pushEnabled": {
"type": "boolean"
},
"defaultTtlSeconds": {
"type": "integer",
"minimum": 0,
"maximum": 259200
},
"quietHoursSupported": {
"type": "boolean"
},
"suppressPushWhenActiveInConversation": {
"type": "boolean"
},
"pushFanoutMode": {
"type": "string",
"enum": [
"all_active_devices"
]
},
"appOrigin": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"providerRoutingMode",
"pushEnabled",
"defaultTtlSeconds",
"quietHoursSupported",
"suppressPushWhenActiveInConversation",
"pushFanoutMode",
"appOrigin"
],
"properties": {
"providerRoutingMode": {
"type": "string",
"enum": [
"managed",
"disabled"
]
},
"pushEnabled": {
"type": "boolean"
},
"defaultTtlSeconds": {
"type": "integer",
"minimum": 0,
"maximum": 259200
},
"quietHoursSupported": {
"type": "boolean"
},
"suppressPushWhenActiveInConversation": {
"type": "boolean"
},
"pushFanoutMode": {
"type": "string",
"enum": [
"all_active_devices"
]
},
"appOrigin": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 2048,
"pattern": "^https://[A-Za-z0-9.-]+(:[0-9]{1,5})?$|^http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?$"
},
{
"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/chat/admin/push-configuration/test
Run tenant chat push readiness check
Return a non-delivery readiness summary for tenant-scoped chat push configuration and a target user.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"targetUserId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"targetUserId",
"pushEnabled",
"providerRoutingMode",
"activeDeviceCount",
"hasActiveDevices",
"queuedDeliveryCount",
"failedDeliveryCount"
],
"properties": {
"targetUserId": {
"type": "string",
"format": "uuid"
},
"pushEnabled": {
"type": "boolean"
},
"providerRoutingMode": {
"type": "string",
"enum": [
"managed",
"disabled"
]
},
"activeDeviceCount": {
"type": "integer",
"minimum": 0
},
"hasActiveDevices": {
"type": "boolean"
},
"queuedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"failedDeliveryCount": {
"type": "integer",
"minimum": 0
}
},
"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/chat/admin/push-deliveries
List tenant chat push deliveries
Return the tenant-scoped push delivery diagnostics list. Read access is limited to tenant admins and system admins.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"conversationId",
"provider",
"status",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"conversationId": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"sending",
"sent",
"delivered",
"suppressed",
"failed"
]
},
"errorCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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/admin/statistics
Get tenant chat admin statistics
Return a reduced tenant-wide operational statistics set for chat conversations, seven-day message volume, unread state, and push-delivery backlog/failures. Read access is limited to tenant admins and system admins.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"conversationCount",
"messagesLast7d",
"unreadMembershipCount",
"queuedDeliveryCount",
"failedDeliveryCount"
],
"properties": {
"conversationCount": {
"type": "integer",
"minimum": 0
},
"messagesLast7d": {
"type": "integer",
"minimum": 0
},
"unreadMembershipCount": {
"type": "integer",
"minimum": 0
},
"queuedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"failedDeliveryCount": {
"type": "integer",
"minimum": 0
}
},
"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
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": {
"code": {
"type": "string",
"pattern": "^[A-Z]{2,3}$",
"description": "Universal country code: ISO 3166-1 alpha-2 when available, else alpha-3. Primary key.",
"example": "CH"
},
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"nullable": true,
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters). Null for entities without an official alpha-2 code.",
"example": "CH"
},
"numeric_code": {
"type": "string",
"pattern": "^[0-9]{3}$",
"nullable": true,
"description": "ISO 3166-1 numeric country code (3 digits). Null when unavailable.",
"example": "756"
},
"cca3": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"description": "ISO 3166-1 alpha-3 country code (3 uppercase letters)",
"example": "CHE"
},
"emoji": {
"type": "string",
"nullable": true,
"description": "Flag emoji for the country",
"example": "🇨🇭"
},
"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": "PNG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/png)",
"example": "/api/v1/public/flags/ch/png"
},
"flag_svg": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "SVG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/svg)",
"example": "/api/v1/public/flags/ch/svg"
},
"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": [
"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 universal code: ISO 3166-1 alpha-2 when available, else alpha-3 (e.g., CH, DE, ABK). 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": {
"code": {
"type": "string",
"pattern": "^[A-Z]{2,3}$",
"description": "Universal country code: ISO 3166-1 alpha-2 when available, else alpha-3. Primary key.",
"example": "CH"
},
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"nullable": true,
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters). Null for entities without an official alpha-2 code.",
"example": "CH"
},
"numeric_code": {
"type": "string",
"pattern": "^[0-9]{3}$",
"nullable": true,
"description": "ISO 3166-1 numeric country code (3 digits). Null when unavailable.",
"example": "756"
},
"cca3": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"nullable": true,
"description": "ISO 3166-1 alpha-3 country code (3 uppercase letters)",
"example": "CHE"
},
"emoji": {
"type": "string",
"nullable": true,
"description": "Flag emoji for the country",
"example": "🇨🇭"
},
"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": "PNG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/png)",
"example": "/api/v1/public/flags/ch/png"
},
"flag_svg": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "SVG flag image URL (self-hosted, served by the backend at /api/v1/public/flags/:code/svg)",
"example": "/api/v1/public/flags/ch/svg"
},
"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": [
"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
Domains
GET
/api/v1/system/domains/azure-setup
Get Azure whitelabel domain manual setup diagnostics
System admin only. Returns PVE domain status, DNS checks, and manual Azure Container Apps custom-domain setup commands.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"environment": {
"type": "string",
"enum": [
"development",
"integration",
"production"
],
"description": "Backend application environment"
},
"platformApiHost": {
"type": "string",
"description": "Canonical platform API hostname for tenant CNAMEs"
},
"azure": {
"type": "object",
"properties": {
"subscriptionId": {
"type": "string",
"description": "Azure subscription ID or placeholder"
},
"resourceGroup": {
"type": "string",
"description": "Azure resource group for backend Container App"
},
"containerAppName": {
"type": "string",
"description": "Azure Container App name for this environment"
},
"defaultHostnameCommand": {
"type": "string",
"description": "Command to read the Container App generated hostname"
},
"verificationIdCommand": {
"type": "string",
"description": "Command to read the Container App custom-domain verification ID"
},
"listBindingsCommand": {
"type": "string",
"description": "Command to list existing Container App custom domain bindings"
},
"portalUrl": {
"type": "string",
"description": "Azure Portal URL for the Container App custom domains blade"
}
},
"required": [
"subscriptionId",
"resourceGroup",
"containerAppName",
"defaultHostnameCommand",
"verificationIdCommand",
"listBindingsCommand",
"portalUrl"
],
"additionalProperties": false
},
"domains": {
"type": "array",
"items": {
"type": "object",
"properties": {
"domainId": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "Tenant domain row ID when configured in PVE"
},
"tenantId": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "Owning tenant ID when configured in PVE"
},
"tenantName": {
"type": [
"null",
"string"
],
"description": "Owning tenant display name when known"
},
"domain": {
"type": "string",
"description": "Custom API domain"
},
"pveStatus": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired",
"not_configured"
],
"description": "PVE tenant-domain verification state"
},
"sslStatus": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired",
"unknown"
],
"description": "Stored PVE SSL/certificate state"
},
"expectedCnameTarget": {
"type": "string",
"description": "PVE expected API CNAME target for this environment"
},
"cnameTarget": {
"type": [
"null",
"string"
],
"description": "Live CNAME target returned by DNS lookup"
},
"cnameMatchesExpected": {
"type": [
"null",
"boolean"
],
"description": "Whether live CNAME matches the PVE expected target"
},
"asuidHost": {
"type": "string",
"description": "Azure domain verification TXT record host"
},
"asuidTxtRecords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Live asuid TXT record values returned by DNS lookup"
},
"commands": {
"type": "object",
"properties": {
"addHostname": {
"type": "string",
"description": "Azure CLI command to add the custom hostname"
},
"bindCertificate": {
"type": "string",
"description": "Azure CLI command to bind an environment-managed certificate"
},
"showBinding": {
"type": "string",
"description": "Azure CLI command to inspect this hostname binding"
},
"tlsProbe": {
"type": "string",
"description": "Command to validate HTTPS/TLS for this hostname"
},
"corsProbe": {
"type": "string",
"description": "Command to validate CORS preflight through this hostname"
}
},
"required": [
"addHostname",
"bindCertificate",
"showBinding",
"tlsProbe",
"corsProbe"
],
"additionalProperties": false
},
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Stable check identifier"
},
"label": {
"type": "string",
"description": "Human-readable check label"
},
"status": {
"type": "string",
"enum": [
"pass",
"warning",
"fail",
"manual",
"unknown"
],
"description": "Current check state"
},
"detail": {
"type": "string",
"description": "Diagnostic detail and recommended action"
}
},
"required": [
"key",
"label",
"status",
"detail"
],
"additionalProperties": false
},
"description": "Ordered setup/checklist states for this domain"
}
},
"required": [
"domainId",
"tenantId",
"tenantName",
"domain",
"pveStatus",
"sslStatus",
"expectedCnameTarget",
"cnameTarget",
"cnameMatchesExpected",
"asuidHost",
"asuidTxtRecords",
"commands",
"checks"
],
"additionalProperties": false
},
"description": "Configured or requested custom domains with diagnostics"
},
"manualSteps": {
"type": "array",
"items": {
"type": "string"
},
"description": "Provider-side manual setup steps"
},
"validationCommands": {
"type": "array",
"items": {
"type": "string"
},
"description": "Commands to validate DNS, Azure binding, TLS, and CORS after setup"
}
},
"required": [
"environment",
"platformApiHost",
"azure",
"domains",
"manualSteps",
"validationCommands"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Export/Import
GET
/api/v1/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",
"tenant"
],
"description": "Entity type this definition applies to"
},
"schemaDefinition": {
"type": "object",
"description": "Canonical nested schema definition for the type",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"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",
"tenant"
],
"description": "Entity type this definition applies to"
},
"schemaDefinition": {
"type": "object",
"description": "Canonical nested schema definition for the type",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"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",
"tenant"
]
},
"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
GET
/api/v1/secure/admin/external-apis/openrouter/models
List OpenRouter models
Returns the current OpenRouter model catalog for text or image tasks so the admin GUI can restrict selection to supported models only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"task": {
"type": "string",
"enum": [
"text",
"image"
]
},
"total": {
"type": "integer"
},
"models": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Canonical OpenRouter model identifier."
},
"name": {
"type": "string",
"description": "Human-readable model name."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"context_length": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"prompt_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"completion_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"image_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"request_price": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"is_free": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"description",
"context_length",
"prompt_price",
"completion_price",
"image_price",
"request_price",
"is_free"
],
"additionalProperties": false
}
}
},
"required": [
"task",
"total",
"models"
],
"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
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"
},
"targetId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"providerName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"providerPath": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sizeBytes": {
"type": "number"
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"publicUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"lastAccessedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"referenceCount": {
"type": "number"
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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
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 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/files/{fileId}/move
Move file
Move file to different storage provider
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"targetId"
],
"properties": {
"targetId": {
"type": "string",
"format": "uuid",
"description": "Canonical storage target ID"
}
},
"additionalProperties": false
}
📤 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/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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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",
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "Explicit file IDs to migrate"
},
"sourceTargetId": {
"type": "string",
"format": "uuid",
"description": "Source storage target ID used to migrate all files currently mapped to that target"
},
"targetId": {
"type": "string",
"format": "uuid",
"description": "Canonical destination storage target ID. Omit to use the tenant storage distribution chain."
}
},
"anyOf": [
{
"required": [
"fileIds"
]
},
{
"required": [
"sourceTargetId"
]
}
],
"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"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/default-tenant-storage
Create default tenant storage migration job
Create a migration job that moves existing tenant files into the tenant-owned default storage target
📤 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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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/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"
},
"mediaFileId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenantId": {
"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
},
"targetId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"providerName": {
"type": "string"
},
"providerType": {
"type": "string",
"nullable": true
},
"providerAccess": {
"type": "string",
"enum": [
"public",
"private"
],
"nullable": true
},
"providerPath": {
"type": "string"
},
"publicUrl": {
"type": "string",
"nullable": true
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"lastAccessedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"referenceCount": {
"type": "number"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"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/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
}
},
"byTarget": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"sizeBytes": {
"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
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"
},
"targetId": {
"type": "string",
"format": "uuid"
},
"providerPath": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string"
}
},
"required": [
"fileId",
"targetId",
"providerPath",
"publicUrl",
"sizeBytes"
],
"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
Flags (Public)
GET
/api/v1/public/flags/{iso}/{format}
Get country flag image
Returns a self-hosted PNG or SVG flag image for a universal country code (ISO 3166-1 alpha-2 when available, else alpha-3). Images are populated during reference-data sync. Returns 404 if not yet synced.
📤 RESPONSE 200
Inline Schema
Response: Flag image binary
Schema: Flag image binary
{
"description": "Flag image binary",
"type": "string"
}
📤 RESPONSE 400
- Invalid ISO code or format
→ See StandardErrorResponse
Note: Invalid ISO code or format
📤 RESPONSE 404
- Flag not found — sync may not have run yet
→ See StandardErrorResponse
Note: Flag not found — sync may not have run yet
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,3}$"
},
"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
GET
/api/v1/secure/geo/network
Resolve network-based geo country information
Resolve the current request country from trusted edge headers and normalized network metadata.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"ok",
"error"
]
},
"message": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"cloudflare-header",
"trusted-forwarded-ip",
"socket-ip",
"unknown"
]
},
"precision": {
"type": "string",
"enum": [
"country",
"approximate",
"unknown"
]
},
"clientIp": {
"type": "string",
"nullable": true
},
"country": {
"type": "object",
"properties": {
"alpha2": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"alpha3": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"nullable": true
},
"name": {
"type": "string"
},
"region": {
"type": "string",
"nullable": true
}
},
"required": [
"alpha2",
"alpha3",
"name",
"region"
],
"additionalProperties": false,
"nullable": true
},
"languages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"name": {
"type": "string"
},
"localName": {
"type": "string"
}
},
"required": [
"code",
"name",
"localName"
],
"additionalProperties": false
}
},
"coordinates": {
"type": "object",
"properties": {
"decimal": {
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
"latLng": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"lngLat": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"geoJsonPoint": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Point"
]
},
"coordinates": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": [
"type",
"coordinates"
],
"additionalProperties": false
}
},
"required": [
"decimal",
"latLng",
"lngLat",
"geoJsonPoint"
],
"additionalProperties": false,
"nullable": true
},
"network": {
"type": "object",
"properties": {
"trustedHeaders": {
"type": "array",
"items": {
"type": "string"
}
},
"countryHeader": {
"type": "string",
"nullable": true
},
"provider": {
"type": "string",
"enum": [
"cloudflare",
"ipinfo"
],
"nullable": true
},
"socketIp": {
"type": "string",
"nullable": true
},
"forwardedIp": {
"type": "string",
"nullable": true
},
"normalizedCountryCode": {
"type": "string",
"pattern": "^[A-Z]{2,3}$",
"nullable": true
}
},
"required": [
"trustedHeaders",
"countryHeader",
"provider",
"socketIp",
"forwardedIp",
"normalizedCountryCode"
],
"additionalProperties": false
}
},
"required": [
"state",
"source",
"precision",
"clientIp",
"country",
"languages",
"coordinates",
"network"
],
"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/geo/network-config
Resolve effective geo network config
Resolve the effective geo network config for the current request using country, tenant default, and system default fallback.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"ok",
"error"
]
},
"message": {
"type": "string"
},
"detection": {
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"ok",
"error"
]
},
"message": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"cloudflare-header",
"trusted-forwarded-ip",
"socket-ip",
"unknown"
]
},
"precision": {
"type": "string",
"enum": [
"country",
"approximate",
"unknown"
]
},
"clientIp": {
"type": "string",
"nullable": true
},
"country": {
"type": "object",
"properties": {
"alpha2": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"alpha3": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"nullable": true
},
"name": {
"type": "string"
},
"region": {
"type": "string",
"nullable": true
}
},
"required": [
"alpha2",
"alpha3",
"name",
"region"
],
"additionalProperties": false,
"nullable": true
},
"languages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"name": {
"type": "string"
},
"localName": {
"type": "string"
}
},
"required": [
"code",
"name",
"localName"
],
"additionalProperties": false
}
},
"coordinates": {
"type": "object",
"properties": {
"decimal": {
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
"latLng": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"lngLat": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"geoJsonPoint": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Point"
]
},
"coordinates": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": [
"type",
"coordinates"
],
"additionalProperties": false
}
},
"required": [
"decimal",
"latLng",
"lngLat",
"geoJsonPoint"
],
"additionalProperties": false,
"nullable": true
},
"network": {
"type": "object",
"properties": {
"trustedHeaders": {
"type": "array",
"items": {
"type": "string"
}
},
"countryHeader": {
"type": "string",
"nullable": true
},
"provider": {
"type": "string",
"enum": [
"cloudflare",
"ipinfo"
],
"nullable": true
},
"socketIp": {
"type": "string",
"nullable": true
},
"forwardedIp": {
"type": "string",
"nullable": true
},
"normalizedCountryCode": {
"type": "string",
"pattern": "^[A-Z]{2,3}$",
"nullable": true
}
},
"required": [
"trustedHeaders",
"countryHeader",
"provider",
"socketIp",
"forwardedIp",
"normalizedCountryCode"
],
"additionalProperties": false
}
},
"required": [
"state",
"source",
"precision",
"clientIp",
"country",
"languages",
"coordinates",
"network"
],
"additionalProperties": false
},
"appliedConfig": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
},
"properties": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"type": "string",
"format": "uuid",
"nullable": true
},
"matchType": {
"type": "string",
"enum": [
"country",
"tenant-default",
"system-default"
]
}
},
"required": [
"id",
"tenantId",
"name",
"description",
"isDefault",
"typeDefinitionId",
"countryCodes",
"properties",
"createdAt",
"updatedAt",
"createdBy",
"matchType"
],
"additionalProperties": false,
"nullable": true
},
"typeDefinition": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"typeName": {
"type": "string"
},
"label": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"isSystem": {
"type": "boolean"
}
},
"required": [
"id",
"typeName",
"label",
"tenantId",
"isSystem"
],
"additionalProperties": false,
"nullable": true
},
"properties": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"state",
"detection",
"appliedConfig",
"typeDefinition",
"properties"
],
"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/geo/network-configs
List geo network configs
List tenant geo network configs and the available tenant/system type definitions used to validate their properties payload.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"configs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
},
"properties": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"id",
"tenantId",
"name",
"description",
"isDefault",
"typeDefinitionId",
"countryCodes",
"properties",
"createdAt",
"updatedAt",
"createdBy"
],
"additionalProperties": false
}
},
"availableTypeDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"typeName": {
"type": "string"
},
"label": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"isSystem": {
"type": "boolean"
}
},
"required": [
"id",
"typeName",
"label",
"tenantId",
"isSystem"
],
"additionalProperties": false
}
}
},
"required": [
"configs",
"availableTypeDefinitions"
],
"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/geo/network-configs
Create a geo network config
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"properties": {
"type": "object",
"additionalProperties": true
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
}
},
"required": [
"name"
],
"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",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
},
"properties": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"id",
"tenantId",
"name",
"description",
"isDefault",
"typeDefinitionId",
"countryCodes",
"properties",
"createdAt",
"updatedAt",
"createdBy"
],
"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/geo/network-configs/{configId}
Delete a geo network config
📤 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
PATCH
/api/v1/secure/geo/network-configs/{configId}
Update a geo network config
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"properties": {
"type": "object",
"additionalProperties": true
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
}
},
"required": [
"name"
],
"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",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"nullable": true
},
"isDefault": {
"type": "boolean"
},
"typeDefinitionId": {
"type": "string",
"format": "uuid"
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z]{2,3}$"
}
},
"properties": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"required": [
"id",
"tenantId",
"name",
"description",
"isDefault",
"typeDefinitionId",
"countryCodes",
"properties",
"createdAt",
"updatedAt",
"createdBy"
],
"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/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"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"user_id",
"email",
"displayName",
"fullName",
"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
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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",
"displayName",
"fullName",
"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"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"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": "Scheduler active-state alias mirrored in status payloads."
}
},
"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_id": {
"type": "string"
},
"job_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"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"
}
]
},
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"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_id": {
"type": "string"
},
"job_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"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"
}
]
},
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"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,3}$",
"nullable": true,
"description": "Country code (alpha-2 or alpha-3) 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,3}$",
"nullable": true,
"description": "Country code (alpha-2 or alpha-3) 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 system storage 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"
},
"triage": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "string"
}
},
"patterns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"intent": {
"type": "string"
},
"firstTools": {
"type": "array",
"items": {
"type": "string"
}
},
"thenTools": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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
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/services/media/{id}
Get media file details
Retrieve a specific media file together with its stored metadata. Use GET /api/v1/services/media/:id/version for client cache-version checks.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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/{id}
Update media filename
Update the display filename used by media details and file browser search without moving the stored object.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"original_filename"
],
"properties": {
"original_filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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}/content
Get media content
Serve signed media content through backend-owned URLs.
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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/services/media/{id}/crop-intent
Update crop intent for the current media version
Persist crop intent, invalidate current derivatives, and trigger re-rendering for current-version media outputs.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"crop_intent"
],
"properties": {
"crop_intent": {
"anyOf": [
{
"type": "object",
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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}/derivative
Select media derivative delivery URL
Return a signed URL for the requested image derivative selector.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"media_file_id",
"version",
"requested",
"selected",
"repairQueued"
],
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"requested": {
"type": "object",
"required": [
"source",
"size",
"format"
],
"properties": {
"source": {
"type": "string",
"enum": [
"derivative"
]
},
"size": {
"anyOf": [
{
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
{
"type": "null"
}
]
},
"format": {
"anyOf": [
{
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"selected": {
"anyOf": [
{
"type": "object",
"required": [
"source",
"url",
"fallbackReason"
],
"properties": {
"source": {
"type": "string",
"enum": [
"derivative"
]
},
"url": {
"type": "string",
"format": "uri"
},
"fallbackReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"derivative": {
"anyOf": [
{
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"repairQueued": {
"type": "boolean"
},
"repairStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"queued",
"deferred"
]
},
{
"type": "null"
}
]
},
"repairReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"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}/derivatives
List media image derivatives
List generated image derivative and thumbnail records for inspection and client selection.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
},
"total": {
"type": "number",
"minimum": 0
}
},
"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
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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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",
"description": "Media file identifier for id-addressable manifest refresh operations."
},
"version": {
"type": "number",
"minimum": 1
},
"previous_version": {
"type": "number",
"minimum": 0,
"description": "Version that was current before regeneration promoted a new version (cache-busting)."
},
"thumbnails": {
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the selected version."
}
},
"required": [
"media_file_id",
"version",
"thumbnails",
"thumbnails_ready"
],
"additionalProperties": false
}
},
"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",
"description": "Media file identifier for id-addressable manifest refresh operations."
},
"version": {
"type": "number",
"minimum": 1
},
"previous_version": {
"type": "number",
"minimum": 0,
"description": "Version that was current before regeneration promoted a new version (cache-busting)."
},
"thumbnails": {
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the selected version."
}
},
"required": [
"media_file_id",
"version",
"thumbnails",
"thumbnails_ready"
],
"additionalProperties": false
}
},
"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}/version
Get media cache version
Return the canonical cache-version state for client image refresh checks without loading media bytes or derivative URLs. Missing or deleted media returns 404; this endpoint never returns a null version marker.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"mediaFileId",
"tenantId",
"version",
"versionUpdatedAt",
"isReady",
"currentVersion",
"currentVersionReady",
"currentVersionState",
"requiredDerivatives",
"completedDerivatives",
"pendingDerivatives",
"failedDerivatives"
],
"properties": {
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1,
"description": "Latest cache-safe version clients should use for image cache refresh checks. Missing or deleted media returns 404 instead of a null version."
},
"versionUpdatedAt": {
"type": "string",
"format": "date-time"
},
"isReady": {
"type": "boolean",
"description": "True when the returned version is ready for client cache refresh."
},
"currentVersion": {
"type": "number",
"minimum": 1,
"description": "Newest stored media version. This can be ahead of the cache-safe version while derivatives are processing."
},
"currentVersionReady": {
"type": "boolean",
"description": "True when newest stored version has all required thumbnail derivatives."
},
"currentVersionState": {
"type": "string",
"enum": [
"ready",
"processing",
"failed"
]
},
"processingVersion": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"requiredDerivatives": {
"type": "number",
"minimum": 0
},
"completedDerivatives": {
"type": "number",
"minimum": 0
},
"pendingDerivatives": {
"type": "number",
"minimum": 0
},
"failedDerivatives": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
}
},
"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 upload/version history for diagnostics and management. Use GET /api/v1/services/media/:id/version for client cache refresh checks.
📤 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",
"description": "Referenced media file identifier. Use this field, not the link id, to load media manifests and detail records."
},
"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",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
},
"additionalProperties": false
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
}
},
"additionalProperties": true,
"description": "File metadata (EXIF, dimensions, crop intent, 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",
"description": "Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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",
"description": "Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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
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
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",
"description": "Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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",
"description": "Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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",
"description": "Entity-media link DTO with embedded canonical media payload. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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": [
"link_id",
"sort_order"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier used for reorder operations."
},
"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",
"description": "Canonical entity-media link DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes. Entity-media link rows expose two identifiers: link_id is the entity-media link identifier, while media_file_id is the referenced media file identifier used for media detail, version, and thumbnail manifest lookups.",
"required": [
"link_id",
"tenantId",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by"
],
"properties": {
"link_id": {
"type": "string",
"format": "uuid",
"description": "Entity-media link identifier. This is not the referenced media file id."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid",
"description": "Referenced media file identifier. Use this field for media detail, version, and thumbnail manifest lookups."
},
"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
GET
/api/v1/services/media/integrity/issues
List media integrity issues
Find broken media links, missing thumbnails, and stale uploaded avatar references for the current tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"issues",
"summary"
],
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue_key",
"issue_type",
"detail",
"link_id",
"entity_type",
"entity_id",
"entity_name",
"media_file_id",
"media_name",
"media_preview_url",
"is_main",
"missing_entity",
"missing_media",
"user_id",
"user_name",
"current_avatar_url",
"created_at",
"consistency_types",
"repairability"
],
"properties": {
"issue_key": {
"type": "string"
},
"issue_type": {
"type": "string",
"enum": [
"broken_link",
"missing_thumbnail",
"broken_thumbnail",
"stale_user_avatar",
"inconsistent_media"
]
},
"detail": {
"type": "string"
},
"link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"entity_type": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
}
]
},
"entity_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"entity_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"media_file_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"media_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"media_preview_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"is_main": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"missing_entity": {
"type": "boolean"
},
"missing_media": {
"type": "boolean"
},
"user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"user_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"current_avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"created_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"consistency_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"missing_mapping",
"path_mismatch",
"version_mismatch",
"missing_version_history",
"bucket_metadata_mismatch",
"stale_thumbnail_metadata",
"thumbnail_colocation_drift",
"storage_object_missing"
]
}
},
"repairability": {
"type": "string",
"enum": [
"repairable",
"fatal"
]
}
}
}
},
"summary": {
"type": "object",
"required": [
"total_issues",
"broken_links",
"missing_thumbnails",
"broken_thumbnails",
"inconsistent_media",
"missing_entity_links",
"missing_media_links",
"stale_user_avatars",
"consistency"
],
"properties": {
"total_issues": {
"type": "number",
"minimum": 0
},
"broken_links": {
"type": "number",
"minimum": 0
},
"missing_thumbnails": {
"type": "number",
"minimum": 0
},
"broken_thumbnails": {
"type": "number",
"minimum": 0
},
"inconsistent_media": {
"type": "number",
"minimum": 0
},
"missing_entity_links": {
"type": "number",
"minimum": 0
},
"missing_media_links": {
"type": "number",
"minimum": 0
},
"stale_user_avatars": {
"type": "number",
"minimum": 0
},
"consistency": {
"type": "object",
"required": [
"total_issues",
"repairable_issues",
"fatal_issues",
"missing_mappings",
"path_mismatches",
"version_mismatches",
"missing_version_history",
"stale_bucket_metadata",
"stale_thumbnail_metadata",
"thumbnail_colocation_drift",
"storage_object_missing"
],
"properties": {
"total_issues": {
"type": "number",
"minimum": 0
},
"repairable_issues": {
"type": "number",
"minimum": 0
},
"fatal_issues": {
"type": "number",
"minimum": 0
},
"missing_mappings": {
"type": "number",
"minimum": 0
},
"path_mismatches": {
"type": "number",
"minimum": 0
},
"version_mismatches": {
"type": "number",
"minimum": 0
},
"missing_version_history": {
"type": "number",
"minimum": 0
},
"stale_bucket_metadata": {
"type": "number",
"minimum": 0
},
"stale_thumbnail_metadata": {
"type": "number",
"minimum": 0
},
"thumbnail_colocation_drift": {
"type": "number",
"minimum": 0
},
"storage_object_missing": {
"type": "number",
"minimum": 0
}
}
}
}
}
}
}
},
"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/integrity/issues/repair
Repair media integrity issue
Repair one media integrity issue by unlinking, relinking, or clearing a stale uploaded avatar.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"unlink",
"relink",
"clear_user_avatar"
]
},
"link_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"allOf": [
{
"if": {
"properties": {
"action": {
"enum": [
"unlink"
]
}
}
},
"then": {
"required": [
"link_id"
]
}
},
{
"if": {
"properties": {
"action": {
"enum": [
"relink"
]
}
}
},
"then": {
"required": [
"link_id",
"entity_type",
"entity_id"
]
}
},
{
"if": {
"properties": {
"action": {
"enum": [
"clear_user_avatar"
]
}
}
},
"then": {
"required": [
"user_id"
]
}
}
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"action",
"repaired"
],
"properties": {
"action": {
"type": "string",
"enum": [
"unlink",
"relink",
"clear_user_avatar"
]
},
"repaired": {
"type": "boolean"
},
"link_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
}
}
},
"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/integrity/issues/repair-all
Repair all safe media integrity issues
Queue a background repair job that removes broken links, clears stale uploaded avatars, and regenerates broken thumbnails for the selected tenant.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"repair_all_safe"
]
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"probe_limit": {
"type": "integer",
"minimum": 1,
"maximum": 25
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"job_id",
"job_name",
"correlation_id",
"status",
"tenantId"
],
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"job_name": {
"type": "string"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": [
"queued"
]
},
"tenantId": {
"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
GET
/api/v1/services/media/integrity/media/{id}
Get per-image media consistency
Run storage, links, thumbnails, version, and API consistency checks for one media file.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"mediaFileId",
"tenantId",
"checks",
"summary",
"thumbnailFiles"
],
"properties": {
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"checks": {
"type": "array",
"items": {
"type": "object",
"required": [
"moduleId",
"title",
"detail",
"severity"
],
"properties": {
"moduleId": {
"type": "string",
"enum": [
"storage",
"links",
"thumbnails",
"version",
"api"
]
},
"title": {
"type": "string",
"minLength": 1
},
"detail": {
"type": "string",
"minLength": 1
},
"severity": {
"type": "string",
"enum": [
"success",
"warning",
"danger"
]
},
"fixAction": {
"anyOf": [
{
"type": "string",
"enum": [
"regenerate-thumbnails"
]
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"summary": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks",
"modules"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
},
"modules": {
"type": "object",
"required": [
"storage",
"links",
"thumbnails",
"version",
"api"
],
"properties": {
"storage": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
},
"links": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
},
"thumbnails": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
},
"version": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
},
"api": {
"type": "object",
"required": [
"totalChecks",
"failingChecks",
"repairableChecks"
],
"properties": {
"totalChecks": {
"type": "number",
"minimum": 0
},
"failingChecks": {
"type": "number",
"minimum": 0
},
"repairableChecks": {
"type": "number",
"minimum": 0
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"thumbnailFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"format",
"storagePath",
"expected",
"hasDerivativeRow",
"existsInStorage",
"sizeBytes",
"width",
"height",
"status"
],
"properties": {
"variantKey": {
"type": "string",
"minLength": 1
},
"format": {
"type": "string",
"minLength": 1
},
"storagePath": {
"type": "string",
"minLength": 1
},
"expected": {
"type": "boolean"
},
"hasDerivativeRow": {
"type": "boolean"
},
"existsInStorage": {
"type": "boolean"
},
"sizeBytes": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"width": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"height": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"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",
"description": "Canonical media DTO. Media API payloads intentionally keep the platform-standard camelCase tenantId while established media and relation storage-backed fields remain snake_case. Thumbnail derivative leaf DTOs are a separate camelCase contract and use fields like mimeType, aspectRatio, and sizeBytes.",
"required": [
"id",
"tenantId",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"thumbnails_ready",
"has_webp_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Media file identifier. Use this id in /media/{id}, /media/{id}/version, and /media/{id}/thumbnails."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media relation fields remain snake_case."
},
"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,
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe refresh checks."
},
"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"
},
"thumbnails_ready": {
"type": "array",
"items": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"description": "Canonical thumbnail sizes with at least one completed derivative for the current version."
},
"has_webp_thumbnails": {
"type": "boolean",
"description": "Whether WebP thumbnail derivatives exist for the current version"
},
"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"
}
}
}
]
},
"image_properties": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"orientation": {
"type": "number"
},
"density": {
"type": "number"
},
"format": {
"type": "string"
},
"space": {
"type": "string"
},
"channels": {
"type": "number"
},
"hasAlpha": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"date_taken": {
"type": "string",
"format": "date-time"
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"jpeg": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"webp": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
},
"avif": {
"type": "object",
"required": [
"format",
"mimeType",
"url",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status"
],
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1,
"description": "Canonical thumbnail leaf size in bytes. Thumbnail derivative leaf DTOs use camelCase field names."
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
}
}
]
},
"image_derivatives": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"description": "Derivative DTOs are camelCase runtime contracts. Use mediaFileId when joining a derivative back to its parent media file.",
"required": [
"id",
"tenantId",
"mediaFileId",
"version",
"targetId",
"kind",
"variantKey",
"format",
"mimeType",
"storagePath",
"width",
"height",
"aspectRatio",
"sizeBytes",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Derivative identifier. Use mediaFileId, not id, when an endpoint asks for the parent media file identifier."
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Public tenant identifier. PVE API payloads use camelCase tenantId even when adjacent media fields remain snake_case."
},
"mediaFileId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"targetId": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"thumbnail",
"optimized"
]
},
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"format": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg",
"image/webp",
"image/avif"
]
},
"storagePath": {
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
},
"aspectRatio": {
"type": "number",
"minimum": 0
},
"sizeBytes": {
"type": "number",
"minimum": 1
},
"quality": {
"anyOf": [
{
"type": "number",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"targetMet": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed"
]
},
"contentHash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cropMetadata": {
"type": "object",
"properties": {
"source_orientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"target_aspect": {
"type": "number",
"minimum": 0
},
"crop_intent": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"requested_fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"blend_applied": {
"type": "boolean"
},
"crop": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0
},
"y": {
"type": "number",
"minimum": 0
},
"width": {
"type": "number",
"minimum": 1
},
"height": {
"type": "number",
"minimum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"requested_crop": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number",
"minimum": 64
},
"height": {
"type": "number",
"minimum": 64
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"padding_px": {
"type": "object",
"properties": {
"left": {
"type": "number",
"minimum": 0
},
"top": {
"type": "number",
"minimum": 0
},
"right": {
"type": "number",
"minimum": 0
},
"bottom": {
"type": "number",
"minimum": 0
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
}
},
"additionalProperties": true
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
]
},
"image_optimization": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"source",
"optimize",
"formats",
"variants",
"maxWidth",
"maxHeight",
"targetKilobytes",
"quality",
"fit",
"allowUpscale"
],
"properties": {
"source": {
"type": "string",
"enum": [
"tenant-defaults",
"client-request"
]
},
"optimize": {
"type": "boolean"
},
"formats": {
"type": "array",
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantKey",
"targetKilobytes"
],
"properties": {
"variantKey": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"minItems": 1
},
"maxWidth": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"maxHeight": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 2048
},
{
"type": "null"
}
]
},
"targetKilobytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10240
},
{
"type": "null"
}
]
},
"quality": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100
},
{
"type": "null"
}
]
},
"fit": {
"type": "string",
"enum": [
"inside",
"cover",
"contain"
]
},
"allowUpscale": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
},
"crop_intent": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"updatedBy",
"updatedAt"
],
"properties": {
"portrait": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"landscape": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"square": {
"type": "object",
"required": [
"x1",
"y1",
"x2",
"y2"
],
"properties": {
"x1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"y1": {
"type": "number",
"description": "Crop coordinate. Normalized crop width/height must be at least 64px."
},
"x2": {
"type": "number",
"description": "Crop coordinate. Landscape crops must resolve to width > height and portrait crops to width < height."
},
"y2": {
"type": "number",
"description": "Crop coordinate. Out-of-bounds requests must retain at least 50% real-image overlap."
}
},
"additionalProperties": false
},
"sourceOrientation": {
"type": "string",
"enum": [
"portrait",
"square",
"landscape"
]
},
"updatedBy": {
"type": "string",
"format": "uuid"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
]
},
"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
Media Settings
GET
/api/v1/services/media/settings/image-optimization
Get tenant image optimization settings
Return tenant-scoped automatic image optimization settings for upload defaults and client override policy.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"tenantId",
"enabled",
"defaultFormats",
"avifEnabled",
"allowClientOverrides",
"variants",
"entityDefaults",
"cropFill"
],
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"defaultFormats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
},
"avifEnabled": {
"type": "boolean"
},
"allowClientOverrides": {
"type": "boolean"
},
"variants": {
"type": "object",
"required": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
],
"properties": {
"xxs": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"entityDefaults": {
"type": "object",
"required": [
"resource",
"space",
"user"
],
"properties": {
"resource": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"user": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"cropFill": {
"type": "object",
"required": [
"mode",
"colors"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"blur",
"color"
]
},
"colors": {
"type": "object",
"required": [
"jpeg",
"webp",
"avif"
],
"properties": {
"jpeg": {
"type": "string",
"minLength": 1
},
"webp": {
"type": "string",
"minLength": 1
},
"avif": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"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/services/media/settings/image-optimization
Update tenant image optimization settings
Update tenant-scoped automatic image optimization settings and clear the tenant media config cache.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"minProperties": 1,
"properties": {
"enabled": {
"type": "boolean"
},
"defaultFormats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
},
"avifEnabled": {
"type": "boolean"
},
"allowClientOverrides": {
"type": "boolean"
},
"variants": {
"type": "object",
"properties": {
"xxs": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"entityDefaults": {
"type": "object",
"properties": {
"resource": {
"type": "object",
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"user": {
"type": "object",
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"cropFill": {
"type": "object",
"minProperties": 1,
"properties": {
"mode": {
"type": "string",
"enum": [
"blur",
"color"
]
},
"colors": {
"type": "object",
"minProperties": 1,
"properties": {
"jpeg": {
"type": "string",
"minLength": 1
},
"webp": {
"type": "string",
"minLength": 1
},
"avif": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"tenantId",
"enabled",
"defaultFormats",
"avifEnabled",
"allowClientOverrides",
"variants",
"entityDefaults",
"cropFill"
],
"properties": {
"tenantId": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"defaultFormats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
},
"avifEnabled": {
"type": "boolean"
},
"allowClientOverrides": {
"type": "boolean"
},
"variants": {
"type": "object",
"required": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
],
"properties": {
"xxs": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xs": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"sm": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"md": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"lg": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
},
"xl": {
"type": "object",
"required": [
"width",
"height",
"targetKilobytes",
"aspectPolicy",
"formats"
],
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 2048
},
"targetKilobytes": {
"type": "integer",
"minimum": 1,
"maximum": 1536
},
"aspectPolicy": {
"type": "string",
"enum": [
"source",
"square",
"landscape",
"portrait",
"adaptive"
]
},
"formats": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"jpeg",
"webp",
"avif"
]
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"entityDefaults": {
"type": "object",
"required": [
"resource",
"space",
"user"
],
"properties": {
"resource": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"space": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
},
"user": {
"type": "object",
"required": [
"publicUrlVariant",
"thumbnailUrlVariant"
],
"properties": {
"publicUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
},
"thumbnailUrlVariant": {
"type": "string",
"enum": [
"xxs",
"xs",
"sm",
"md",
"lg",
"xl"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"cropFill": {
"type": "object",
"required": [
"mode",
"colors"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"blur",
"color"
]
},
"colors": {
"type": "object",
"required": [
"jpeg",
"webp",
"avif"
],
"properties": {
"jpeg": {
"type": "string",
"minLength": 1
},
"webp": {
"type": "string",
"minLength": 1
},
"avif": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"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
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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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",
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "Explicit file IDs to migrate"
},
"sourceTargetId": {
"type": "string",
"format": "uuid",
"description": "Source storage target ID used to migrate all files currently mapped to that target"
},
"targetId": {
"type": "string",
"format": "uuid",
"description": "Canonical destination storage target ID. Omit to use the tenant storage distribution chain."
}
},
"anyOf": [
{
"required": [
"fileIds"
]
},
{
"required": [
"sourceTargetId"
]
}
],
"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"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/default-tenant-storage
Create default tenant storage migration job
Create a migration job that moves existing tenant files into the tenant-owned default storage target
📤 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"
}
},
"targetId": {
"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"
},
"currentTaskLabel": {
"type": "string",
"nullable": true
},
"destinationMode": {
"type": "string",
"enum": [
"target",
"distribution"
],
"nullable": true
}
},
"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
},
"failureDetails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fileId": {
"type": "string"
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"totalTasks": {
"type": "number"
},
"completedTasks": {
"type": "number"
},
"failedTasks": {
"type": "number"
},
"migratedFiles": {
"type": "number"
},
"failedFiles": {
"type": "number"
},
"consistencyChecks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"preflight",
"postflight"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"totalIssues": {
"type": "number"
},
"repairableIssues": {
"type": "number"
},
"fatalIssues": {
"type": "number"
},
"missingMappings": {
"type": "number"
},
"pathMismatches": {
"type": "number"
},
"versionMismatches": {
"type": "number"
},
"missingVersionHistory": {
"type": "number"
},
"staleBucketMetadata": {
"type": "number"
},
"staleThumbnailMetadata": {
"type": "number"
},
"thumbnailColocationDrift": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"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
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
Notifications
GET
/api/v1/secure/notifications/devices
List notification devices
List the current user notification devices registered in the active tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"deviceUid",
"platform",
"pushProvider",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deviceUid": {
"type": "string"
},
"platform": {
"type": "string",
"enum": [
"web",
"ios",
"android"
]
},
"pushProvider": {
"type": "string",
"enum": [
"webpush",
"apns",
"fcm"
]
},
"status": {
"type": "string",
"enum": [
"active",
"invalid",
"retired"
]
},
"capabilities": {
"type": "object",
"additionalProperties": true
},
"appVersion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"osVersion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastSeenAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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
POST
/api/v1/secure/notifications/devices
Register notification device
Create or refresh the current user notification device binding in the active tenant. For pushProvider="webpush", pushToken must be JSON.stringify(subscription.toJSON()) and include endpoint plus keys.p256dh and keys.auth. Re-registering with the same deviceUid supersedes the previous token.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"deviceUid",
"platform",
"pushProvider",
"pushToken"
],
"properties": {
"deviceUid": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"platform": {
"type": "string",
"enum": [
"web",
"ios",
"android"
]
},
"pushProvider": {
"type": "string",
"enum": [
"webpush",
"apns",
"fcm"
]
},
"pushToken": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Web Push subscriptions must use JSON.stringify(subscription.toJSON()) and include endpoint plus keys (p256dh, auth)."
},
"capabilities": {
"type": "object",
"additionalProperties": true
},
"appVersion": {
"type": "string",
"maxLength": 100
},
"osVersion": {
"type": "string",
"maxLength": 100
},
"locale": {
"type": "string",
"maxLength": 20
},
"timezone": {
"type": "string",
"maxLength": 100
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"deviceUid",
"platform",
"pushProvider",
"status",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"deviceUid": {
"type": "string"
},
"platform": {
"type": "string",
"enum": [
"web",
"ios",
"android"
]
},
"pushProvider": {
"type": "string",
"enum": [
"webpush",
"apns",
"fcm"
]
},
"status": {
"type": "string",
"enum": [
"active",
"invalid",
"retired"
]
},
"capabilities": {
"type": "object",
"additionalProperties": true
},
"appVersion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"osVersion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"locale": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastSeenAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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
DELETE
/api/v1/secure/notifications/devices/{deviceId}
Delete notification device
Delete the current user notification device binding in the active tenant.
📤 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/notifications/devices/webpush-client-config
Get web push client config
Return client-safe Web Push bootstrap values for authenticated browser registration, including whether tenant/runtime webpush is supported and the VAPID public key used to create PushSubscription entries.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"supported",
"publicKey"
],
"properties": {
"supported": {
"type": "boolean"
},
"publicKey": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"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/notifications/inbox
List inbox notifications
List durable inbox notifications for the current user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"items",
"nextCursor",
"unreadCount"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"notificationEventId",
"tenantId",
"userId",
"category",
"priority",
"status",
"title",
"body",
"actionPayload",
"renderPayload",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"status": {
"type": "string",
"enum": [
"unread",
"read",
"archived",
"acknowledged",
"suppressed",
"expired"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"deeplink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"actionPayload": {
"type": "object",
"additionalProperties": true
},
"renderPayload": {
"type": "object",
"additionalProperties": true
},
"readAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archivedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledgedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"unreadCount": {
"type": "integer",
"minimum": 0
}
},
"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/notifications/inbox/{notificationId}
Get inbox notification
Get a single durable inbox notification for the current user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"notificationEventId",
"tenantId",
"userId",
"category",
"priority",
"status",
"title",
"body",
"actionPayload",
"renderPayload",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"status": {
"type": "string",
"enum": [
"unread",
"read",
"archived",
"acknowledged",
"suppressed",
"expired"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"deeplink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"actionPayload": {
"type": "object",
"additionalProperties": true
},
"renderPayload": {
"type": "object",
"additionalProperties": true
},
"readAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archivedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledgedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/notifications/inbox/{notificationId}/acknowledge
Acknowledge notification
Acknowledge an inbox notification that requires explicit user acknowledgment.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"acknowledgedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"notificationEventId",
"tenantId",
"userId",
"category",
"priority",
"status",
"title",
"body",
"actionPayload",
"renderPayload",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"status": {
"type": "string",
"enum": [
"unread",
"read",
"archived",
"acknowledged",
"suppressed",
"expired"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"deeplink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"actionPayload": {
"type": "object",
"additionalProperties": true
},
"renderPayload": {
"type": "object",
"additionalProperties": true
},
"readAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archivedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledgedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/notifications/inbox/{notificationId}/archive-state
Update notification archive state
Archive or restore an inbox notification.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"archived"
],
"properties": {
"archived": {
"type": "boolean"
},
"archivedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"notificationEventId",
"tenantId",
"userId",
"category",
"priority",
"status",
"title",
"body",
"actionPayload",
"renderPayload",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"status": {
"type": "string",
"enum": [
"unread",
"read",
"archived",
"acknowledged",
"suppressed",
"expired"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"deeplink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"actionPayload": {
"type": "object",
"additionalProperties": true
},
"renderPayload": {
"type": "object",
"additionalProperties": true
},
"readAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archivedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledgedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
PATCH
/api/v1/secure/notifications/inbox/{notificationId}/read-state
Update notification read state
Mark an inbox notification as read or unread.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"read"
],
"properties": {
"read": {
"type": "boolean"
},
"readAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"notificationEventId",
"tenantId",
"userId",
"category",
"priority",
"status",
"title",
"body",
"actionPayload",
"renderPayload",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"status": {
"type": "string",
"enum": [
"unread",
"read",
"archived",
"acknowledged",
"suppressed",
"expired"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"deeplink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"actionPayload": {
"type": "object",
"additionalProperties": true
},
"renderPayload": {
"type": "object",
"additionalProperties": true
},
"readAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"archivedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledgedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/notifications/preferences
List notification preferences
List the effective tenant-default and user-override preferences for the current user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"scope",
"category",
"channel",
"enabled",
"quietHours",
"rules",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"scope": {
"type": "string",
"enum": [
"tenant_default",
"user_override"
]
},
"category": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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/notifications/preferences
Update notification preferences
Update user-override notification preferences for the current user.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"preferences"
],
"properties": {
"preferences": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"category",
"channel",
"enabled"
],
"properties": {
"category": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"scope",
"category",
"channel",
"enabled",
"quietHours",
"rules",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"scope": {
"type": "string",
"enum": [
"tenant_default",
"user_override"
]
},
"category": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"enabled": {
"type": "boolean"
},
"quietHours": {
"type": "object",
"additionalProperties": true
},
"rules": {
"type": "object",
"additionalProperties": true
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"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
POST
/api/v1/secure/notifications/realtime/session
Create realtime session
Create a bounded realtime notification session token for the current user.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"token",
"expiresAt",
"transport"
],
"properties": {
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"transport": {
"type": "object",
"required": [
"wsEndpoint",
"useTls"
],
"properties": {
"wsEndpoint": {
"type": "string"
},
"useTls": {
"type": "boolean"
}
},
"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
POST
/api/v1/secure/notifications/realtime/subscriptions
Create realtime notification subscriptions
Create signed realtime channel subscriptions for the requested notification topics.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"topics"
],
"properties": {
"topics": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"subscriptions"
],
"properties": {
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"required": [
"topic",
"channel",
"token",
"expiresAt"
],
"properties": {
"topic": {
"type": "string"
},
"channel": {
"type": "string"
},
"token": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"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/secure/notifications/unread-summary
Get unread summary
Return unread counters for the current user as totalUnreadCount plus per-category entries with latestCreatedAt. This endpoint is the canonical badge source for installed PWAs and mobile-web clients.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"totalUnreadCount",
"categories"
],
"properties": {
"totalUnreadCount": {
"type": "integer",
"minimum": 0
},
"categories": {
"type": "array",
"items": {
"type": "object",
"required": [
"category",
"unreadCount",
"latestCreatedAt"
],
"properties": {
"category": {
"type": "string"
},
"unreadCount": {
"type": "integer",
"minimum": 0
},
"latestCreatedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"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
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"
},
"fullName": {
"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",
"fullName",
"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"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"tenantName": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"tenantId",
"tenantName"
],
"additionalProperties": false
},
"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 server-side callback completion in the platform auth broker"
},
"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
Queue a password reset message for the 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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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,3}$",
"description": "Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"
},
"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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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,3}$",
"description": "Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"
}
}
}
📤 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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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,3}$",
"description": "Country code: alpha-2 or alpha-3 (e.g., CH, ABK)"
}
}
}
📤 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": {
"anyOf": [
{
"type": "object",
"properties": {
"e164": {
"type": "string"
},
"international": {
"type": "string"
},
"national": {
"type": "string"
},
"rfc3966": {
"type": "string"
}
},
"required": [
"e164",
"international",
"national",
"rfc3966"
],
"additionalProperties": false
},
{
"type": "string"
}
],
"description": "Formatted phone number payload (validate: all formats, format endpoint: requested single format)"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"national_number": {
"type": "string",
"description": "National number without country prefix"
},
"extension": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Phone extension if present"
},
"calling_code": {
"type": "string",
"description": "Country calling code (without + prefix)"
},
"type": {
"anyOf": [
{
"type": "string",
"enum": [
"fixed_line",
"mobile",
"fixed_line_or_mobile",
"toll_free",
"premium_rate",
"shared_cost",
"voip",
"personal_number",
"pager",
"uan",
"voicemail",
"unknown"
]
},
{
"type": "null"
}
],
"description": "Normalized line type from libphonenumber-js"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Supported countries (countries endpoint)"
},
"count": {
"type": "number",
"description": "Total result count for list-style responses"
},
"country_name": {
"type": "string",
"description": "Full country name (if available)"
},
"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)"
},
"error": {
"type": "string",
"description": "Validation or parsing error message"
}
},
"required": [],
"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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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 resolved direct-render 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"
],
"description": "Currently active avatar source"
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Resolved avatar URL ready for direct rendering; may be a signed media URL or remote provider URL"
},
"identityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Identity ID when the active source is remote"
}
},
"required": [
"source"
],
"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
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 ready for direct rendering; may be a signed media URL or remote provider 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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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,3}$",
"description": "Country code: ISO 3166-1 alpha-2 when available, else alpha-3 (2–3 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"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenant_name": {
"type": "string"
},
"role": {
"type": "string"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"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",
"metadata",
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
]
},
"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
},
"themeId": {
"type": "string"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string"
},
"mediaId": {
"type": "string",
"format": "uuid"
}
},
"required": []
}
},
"additionalProperties": false
},
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"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",
"metadata",
"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
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/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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"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",
"metadata",
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata — replaces existing object entirely when provided."
},
"options": {
"type": "object",
"properties": {
"foregroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"backgroundColor": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$"
},
"size": {
"type": "integer",
"minimum": 64,
"maximum": 4096
},
"sizeUnit": {
"type": "string",
"enum": [
"px",
"em"
]
},
"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
},
"themeId": {
"type": "string"
},
"printProfile": {
"type": "string",
"enum": [
"STANDARD",
"HI_RES_300DPI",
"HI_RES_600DPI"
]
},
"icon": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"size": {
"type": "string",
"enum": [
"SMALL",
"MEDIUM",
"LARGE"
]
},
"color": {
"type": "string"
},
"mediaId": {
"type": "string",
"format": "uuid"
}
},
"required": []
}
},
"additionalProperties": false
},
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"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",
"metadata",
"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
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- 401 Unauthorized - Authentication required or failed
→ See StandardErrorResponse
Note: 401 Unauthorized - Authentication required or failed
📤 RESPONSE 403
- 403 Forbidden - Insufficient permissions
→ See StandardErrorResponse
Note: 403 Forbidden - Insufficient permissions
📤 RESPONSE 404
- 404 Not Found - Resource does not exist
→ See StandardErrorResponse
Note: 404 Not Found - Resource does not exist
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- 500 Internal Server Error
→ See StandardErrorResponse
Note: 500 Internal Server Error
POST
/api/v1/secure/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}/resolve
Resolve QR code linked target
Resolve a QR code UUID to its linked PVE entities for trusted application backends.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"qrCode": {
"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": "Content encoded in the QR image"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "App-level metadata stored server-side, never encoded in the QR image. Attach userId, externalId, custom tags, etc. Retrieved via UUID lookup after a scan."
},
"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",
"metadata",
"options",
"renderMode",
"accessLevel",
"isVersioned",
"versionCounter",
"createdAt",
"updatedAt"
]
},
"links": {
"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"
]
}
},
"primaryTarget": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"space",
"resource",
"contact",
"user",
"calendar_entry"
],
"description": "Primary linked entity type resolved from QR assignments"
},
"id": {
"type": "integer",
"description": "Linked entity numeric ID when available"
},
"uuid": {
"type": "string",
"format": "uuid",
"description": "Linked entity UUID when available"
},
"linkId": {
"type": "integer",
"description": "QR link row ID that produced this target"
},
"permissionSource": {
"type": "string",
"description": "Permission inheritance source for this assignment"
},
"inheritsPermissions": {
"type": "boolean",
"description": "Whether this assignment inherits entity permissions"
}
},
"required": [
"type",
"linkId",
"inheritsPermissions"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "First linked target for convenience; clients should inspect links when multiple assignments exist"
}
},
"required": [
"qrCode",
"links",
"primaryTarget"
],
"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/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
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",
"description": "Whether the created account must complete email verification before it can be used."
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"id",
"email",
"displayName",
"fullName",
"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
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
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
Resource Move Requests
POST
/api/v1/secure/resources/{id}/move
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"targetSpaceId": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string",
"maxLength": 2000
}
},
"required": [
"targetSpaceId"
],
"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
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/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",
"properties": {
"rejectionReason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"rejectionReason"
],
"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"
}
]
}
},
"additionalProperties": false
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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"
}
]
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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"
},
"subscriptionTypeId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
{
"type": "null"
}
]
},
"subscription": {
"anyOf": [
{
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
{
"type": "null"
}
]
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"categoryIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
],
"description": "Category IDs to link to this resource during create."
},
"tagIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
],
"description": "Tag IDs to link to this resource during create."
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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. When tagIds or categoryIds are provided, the resource taxonomy links are replaced to match the provided IDs.
📥 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"
}
]
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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"
},
"subscriptionTypeId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
{
"type": "null"
}
]
},
"subscription": {
"anyOf": [
{
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
{
"type": "null"
}
]
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"categoryIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
],
"description": "When provided, replaces all category links on the resource with this exact set."
},
"tagIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
{
"type": "null"
}
],
"description": "When provided, replaces all tag links on the resource with this exact set."
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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",
"filter_id",
"level",
"sort_order",
"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",
"properties": {
"category_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"category_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"
},
"categoryId": {
"type": "string",
"format": "uuid"
},
"entityType": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"categoryId",
"entityType",
"entityId",
"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
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}/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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
}
]
}
},
"additionalProperties": false
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive"
],
"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 base-language fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Localized category summaries linked to the tag"
},
"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",
"categories",
"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",
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"tag_name"
],
"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
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/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"
}
]
}
},
"additionalProperties": false
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this resource."
},
"subscription": {
"type": "boolean",
"description": "Whether this resource is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata (includes type-definition fields such as country, price1hAmount, price1hCurrency)"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"space_id",
"current_space_name",
"distanceMeters",
"currentLocation",
"categories",
"tags",
"mediaFileIds",
"created_at",
"updated_at",
"settings",
"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
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/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"
],
"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}/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
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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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"
},
"subscriptionTypeId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
{
"type": "null"
}
]
},
"subscription": {
"anyOf": [
{
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
{
"type": "null"
}
]
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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
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/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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
]
},
"promotionType": {
"type": "string",
"enum": [
"None",
"Effect1",
"Effect2",
"Effect3",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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"
},
"subscriptionTypeId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
{
"type": "null"
}
]
},
"subscription": {
"anyOf": [
{
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
{
"type": "null"
}
]
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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"
},
"sort_order": {
"type": "number",
"description": "Manual sibling ordering within the same parent"
},
"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",
"filter_id",
"level",
"sort_order",
"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",
"properties": {
"category_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"category_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"
},
"categoryId": {
"type": "string",
"format": "uuid"
},
"entityType": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenantId",
"categoryId",
"entityType",
"entityId",
"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
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/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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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",
"CommercialAdd"
],
"default": "None",
"description": "Promotion mode enum. None clears promotion. Effect1, Effect2, and Effect3 are timed highlight variants. CommercialAdd marks commercial promotion mode."
},
"promotionPlacement": {
"type": "string",
"enum": [
"none",
"positionFix",
"positionDynamic",
"categoryPin",
"geoBoost"
],
"default": "none",
"description": "Promotion placement strategy. none disables placement rules. positionFix and positionDynamic map to list placement. categoryPin and geoBoost are contextual placement strategies."
},
"promotionBadge": {
"type": "string",
"enum": [
"none",
"featured",
"verifiedPro",
"fastReply"
],
"default": "none",
"description": "Promotion badge shown in UI contexts."
},
"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."
},
"subscriptionTypeId": {
"type": "integer",
"minimum": 0,
"description": "Subscription type identifier for this space."
},
"subscription": {
"type": "boolean",
"description": "Whether this space is currently managed as a subscription item."
},
"subscriptionStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription start date; null means not scheduled"
},
"subscriptionEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Subscription end date; null means no end date is scheduled"
},
"subscriptionActive": {
"type": "boolean",
"default": false,
"description": "Computed subscription state for the effective check timestamp."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_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",
"promotionPlacement",
"promotionBadge",
"promotionRank",
"promotionStartDate",
"promotionEndDate",
"customOrder",
"subscriptionTypeId",
"subscription",
"subscriptionStartDate",
"subscriptionEndDate",
"subscriptionActive",
"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 base-language fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Localized category summaries linked to the tag"
},
"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",
"categories",
"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",
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"tag_name"
],
"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
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/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
POST
/api/v1/secure/spaces/{id}/visit-metrics/track
Track space detail visit
Records a space detail visit explicitly. Call this asynchronously after the space record is displayed to the user. Use GET /api/v1/secure/spaces/{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/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"
},
"tenants": {
"type": "number",
"description": "Total number of tenants. System admin only."
},
"calendars": {
"type": "number",
"description": "Total number of calendars"
},
"qrCodes": {
"type": "number",
"description": "Total number of QR codes"
},
"typeDefinitions": {
"type": "number",
"description": "Total number of type definitions"
},
"recentChanges24h": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total change events in the period"
},
"created": {
"type": "number",
"description": "Create or add events in the period"
},
"updated": {
"type": "number",
"description": "Update or modify events in the period"
},
"deleted": {
"type": "number",
"description": "Delete or remove events in the period"
}
},
"required": [
"total",
"created",
"updated",
"deleted"
],
"additionalProperties": false
},
"recentChanges7d": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "Total change events in the period"
},
"created": {
"type": "number",
"description": "Create or add events in the period"
},
"updated": {
"type": "number",
"description": "Update or modify events in the period"
},
"deleted": {
"type": "number",
"description": "Delete or remove events in the period"
}
},
"required": [
"total",
"created",
"updated",
"deleted"
],
"additionalProperties": false
}
},
"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/default-tenant-storage/stats
Get default tenant storage stats
Get default tenant 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/default-tenant-storage/status
Get default tenant storage status
Get tenant default 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
GET
/api/v1/secure/storage/distribution-config
Get distribution configuration
Get target-based storage routing configuration and validation metadata for active storage targets
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"strategy": {
"type": "string"
},
"enableDistribution": {
"type": "boolean"
},
"fallbackEnabled": {
"type": "boolean"
},
"targetKind": {
"type": "string",
"enum": [
"bucket",
"container"
]
},
"thumbnailLocationPolicy": {
"type": "string"
},
"routingModel": {
"type": "string",
"enum": [
"provider-first-mapping"
]
},
"placementAuthority": {
"type": "string",
"enum": [
"storage-layer"
]
},
"provider_capabilities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"label": {
"type": "string"
},
"description": {
"type": "string"
},
"deliveryMode": {
"type": "string",
"enum": [
"proxy-only",
"signed-redirect"
]
},
"supportsFallback": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"label": {
"type": "string"
},
"scope": {
"type": "string",
"enum": [
"config",
"credentials"
]
},
"input": {
"type": "string",
"enum": [
"text",
"password"
]
},
"required": {
"type": "boolean"
},
"helpText": {
"type": [
"null",
"string"
]
},
"placeholder": {
"type": [
"null",
"string"
]
}
},
"required": [
"key",
"label",
"scope",
"input",
"required"
],
"additionalProperties": false
}
}
},
"required": [
"provider",
"label",
"description",
"deliveryMode",
"supportsFallback",
"fields"
],
"additionalProperties": false
}
},
"defaultTargetId": {
"type": [
"null",
"string"
]
},
"defaultTarget": {
"type": [
"null",
"string"
]
},
"targets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"scope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"routingMetadata": {
"type": "object",
"properties": {
"placementMode": {
"type": "string",
"enum": [
"provider-first"
]
},
"placementAuthority": {
"type": "string",
"enum": [
"storage-layer"
]
},
"thumbnailPlacement": {
"type": "string",
"enum": [
"same-as-original"
]
}
},
"required": [
"placementMode",
"placementAuthority",
"thumbnailPlacement"
],
"additionalProperties": false
},
"validationMetadata": {
"type": "object",
"properties": {
"allowedMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"allowedMimeTypes"
],
"additionalProperties": false
},
"priority": {
"type": "number"
},
"active": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"scope",
"routingMetadata",
"validationMetadata",
"priority",
"active"
],
"additionalProperties": false
}
},
"thumbnailColocation": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"same-as-original"
]
},
"enforcedBy": {
"type": "string",
"enum": [
"storage-layer"
]
}
},
"required": [
"mode",
"enforcedBy"
],
"additionalProperties": false
},
"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": [
"single-target",
"sequential",
"distributed"
]
},
"fallbackChain": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"defaultTargetId": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"defaultTargetId": {
"type": [
"null",
"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/targets
List storage targets
List readable storage targets accessible to 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"
},
"tenantId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"ownerScope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"readEnabled": {
"type": "boolean"
},
"writeEnabled": {
"type": "boolean"
},
"priority": {
"type": "number"
},
"weight": {
"type": "number"
},
"quotaBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"currentUsageBytes": {
"type": "number"
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"healthStatus": {
"type": "string",
"enum": [
"online",
"degraded",
"offline",
"unknown"
]
},
"lastHealthCheckAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {
"type": "object",
"additionalProperties": true
},
"credentialVersion": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updatedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"ownerScope",
"provider",
"name",
"enabled",
"readEnabled",
"writeEnabled",
"priority",
"weight",
"currentUsageBytes",
"healthStatus",
"config",
"credentialVersion",
"createdAt",
"updatedAt"
],
"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/targets
Create storage target
Create a canonical storage target
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"provider",
"name",
"ownerScope"
],
"properties": {
"tenantId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"ownerScope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"enabled": {
"type": "boolean",
"default": true
},
"readEnabled": {
"type": "boolean",
"default": true
},
"writeEnabled": {
"type": "boolean",
"default": true
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000,
"default": 100
},
"weight": {
"type": "number",
"minimum": 1,
"default": 1
},
"quotaBytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"config": {
"type": "object",
"additionalProperties": true
}
},
"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"
}
]
},
"ownerScope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"readEnabled": {
"type": "boolean"
},
"writeEnabled": {
"type": "boolean"
},
"priority": {
"type": "number"
},
"weight": {
"type": "number"
},
"quotaBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"currentUsageBytes": {
"type": "number"
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"healthStatus": {
"type": "string",
"enum": [
"online",
"degraded",
"offline",
"unknown"
]
},
"lastHealthCheckAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {
"type": "object",
"additionalProperties": true
},
"credentialVersion": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updatedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"ownerScope",
"provider",
"name",
"enabled",
"readEnabled",
"writeEnabled",
"priority",
"weight",
"currentUsageBytes",
"healthStatus",
"config",
"credentialVersion",
"createdAt",
"updatedAt"
],
"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/targets/{target_id}
Delete storage target
Delete a canonical storage target
📤 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
PATCH
/api/v1/secure/storage/targets/{target_id}
Update storage target
Update a canonical storage target
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"enabled": {
"type": "boolean"
},
"readEnabled": {
"type": "boolean"
},
"writeEnabled": {
"type": "boolean"
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000
},
"weight": {
"type": "number",
"minimum": 1
},
"quotaBytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
]
},
"healthStatus": {
"type": "string",
"enum": [
"online",
"degraded",
"offline",
"unknown"
]
},
"lastError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {
"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": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"ownerScope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"readEnabled": {
"type": "boolean"
},
"writeEnabled": {
"type": "boolean"
},
"priority": {
"type": "number"
},
"weight": {
"type": "number"
},
"quotaBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"currentUsageBytes": {
"type": "number"
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"healthStatus": {
"type": "string",
"enum": [
"online",
"degraded",
"offline",
"unknown"
]
},
"lastHealthCheckAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {
"type": "object",
"additionalProperties": true
},
"credentialVersion": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updatedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"ownerScope",
"provider",
"name",
"enabled",
"readEnabled",
"writeEnabled",
"priority",
"weight",
"currentUsageBytes",
"healthStatus",
"config",
"credentialVersion",
"createdAt",
"updatedAt"
],
"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/targets/{target_id}/download/{*}
Download target file
Download file from a canonical storage target
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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/targets/{target_id}/files
List target files
List files in a canonical storage target
📤 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)"
},
"fileId": {
"type": [
"null",
"string"
],
"description": "Mapped stable file ID (null for folders or unmapped files)"
},
"mediaFileId": {
"type": [
"null",
"string"
],
"description": "Canonical media file ID for media-specific actions"
},
"targetId": {
"type": [
"null",
"string"
],
"description": "Canonical storage target ID"
},
"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"
},
"referenceCount": {
"type": "number",
"description": "Number of linked entity references"
},
"created_at": {
"type": [
"null",
"string"
],
"description": "Creation timestamp"
},
"updated_at": {
"type": [
"null",
"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/targets/{target_id}/health/refresh
Refresh storage target health
Run an explicit health check for a storage target and persist the canonical health state
📤 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"
}
]
},
"ownerScope": {
"type": "string",
"enum": [
"system",
"tenant"
]
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"readEnabled": {
"type": "boolean"
},
"writeEnabled": {
"type": "boolean"
},
"priority": {
"type": "number"
},
"weight": {
"type": "number"
},
"quotaBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"currentUsageBytes": {
"type": "number"
},
"maxFileSizeBytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"healthStatus": {
"type": "string",
"enum": [
"online",
"degraded",
"offline",
"unknown"
]
},
"lastHealthCheckAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config": {
"type": "object",
"additionalProperties": true
},
"credentialVersion": {
"type": "number"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updatedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenantId",
"ownerScope",
"provider",
"name",
"enabled",
"readEnabled",
"writeEnabled",
"priority",
"weight",
"currentUsageBytes",
"healthStatus",
"config",
"credentialVersion",
"createdAt",
"updatedAt"
],
"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/targets/{target_id}/thumbnail/{*}
Get target file thumbnail
Get thumbnail for an image file from a canonical storage target
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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}/default-tenant-storage
Update tenant default storage
Update tenant default storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Must remain true for default tenant storage"
},
"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 via direct resource membership or manageable parent spaces.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"space_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"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",
"supabase-scheduler"
]
},
"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/domains/azure-setup
Get Azure whitelabel domain manual setup diagnostics
System admin only. Returns PVE domain status, DNS checks, and manual Azure Container Apps custom-domain setup commands.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"environment": {
"type": "string",
"enum": [
"development",
"integration",
"production"
],
"description": "Backend application environment"
},
"platformApiHost": {
"type": "string",
"description": "Canonical platform API hostname for tenant CNAMEs"
},
"azure": {
"type": "object",
"properties": {
"subscriptionId": {
"type": "string",
"description": "Azure subscription ID or placeholder"
},
"resourceGroup": {
"type": "string",
"description": "Azure resource group for backend Container App"
},
"containerAppName": {
"type": "string",
"description": "Azure Container App name for this environment"
},
"defaultHostnameCommand": {
"type": "string",
"description": "Command to read the Container App generated hostname"
},
"verificationIdCommand": {
"type": "string",
"description": "Command to read the Container App custom-domain verification ID"
},
"listBindingsCommand": {
"type": "string",
"description": "Command to list existing Container App custom domain bindings"
},
"portalUrl": {
"type": "string",
"description": "Azure Portal URL for the Container App custom domains blade"
}
},
"required": [
"subscriptionId",
"resourceGroup",
"containerAppName",
"defaultHostnameCommand",
"verificationIdCommand",
"listBindingsCommand",
"portalUrl"
],
"additionalProperties": false
},
"domains": {
"type": "array",
"items": {
"type": "object",
"properties": {
"domainId": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "Tenant domain row ID when configured in PVE"
},
"tenantId": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "Owning tenant ID when configured in PVE"
},
"tenantName": {
"type": [
"null",
"string"
],
"description": "Owning tenant display name when known"
},
"domain": {
"type": "string",
"description": "Custom API domain"
},
"pveStatus": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired",
"not_configured"
],
"description": "PVE tenant-domain verification state"
},
"sslStatus": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired",
"unknown"
],
"description": "Stored PVE SSL/certificate state"
},
"expectedCnameTarget": {
"type": "string",
"description": "PVE expected API CNAME target for this environment"
},
"cnameTarget": {
"type": [
"null",
"string"
],
"description": "Live CNAME target returned by DNS lookup"
},
"cnameMatchesExpected": {
"type": [
"null",
"boolean"
],
"description": "Whether live CNAME matches the PVE expected target"
},
"asuidHost": {
"type": "string",
"description": "Azure domain verification TXT record host"
},
"asuidTxtRecords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Live asuid TXT record values returned by DNS lookup"
},
"commands": {
"type": "object",
"properties": {
"addHostname": {
"type": "string",
"description": "Azure CLI command to add the custom hostname"
},
"bindCertificate": {
"type": "string",
"description": "Azure CLI command to bind an environment-managed certificate"
},
"showBinding": {
"type": "string",
"description": "Azure CLI command to inspect this hostname binding"
},
"tlsProbe": {
"type": "string",
"description": "Command to validate HTTPS/TLS for this hostname"
},
"corsProbe": {
"type": "string",
"description": "Command to validate CORS preflight through this hostname"
}
},
"required": [
"addHostname",
"bindCertificate",
"showBinding",
"tlsProbe",
"corsProbe"
],
"additionalProperties": false
},
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Stable check identifier"
},
"label": {
"type": "string",
"description": "Human-readable check label"
},
"status": {
"type": "string",
"enum": [
"pass",
"warning",
"fail",
"manual",
"unknown"
],
"description": "Current check state"
},
"detail": {
"type": "string",
"description": "Diagnostic detail and recommended action"
}
},
"required": [
"key",
"label",
"status",
"detail"
],
"additionalProperties": false
},
"description": "Ordered setup/checklist states for this domain"
}
},
"required": [
"domainId",
"tenantId",
"tenantName",
"domain",
"pveStatus",
"sslStatus",
"expectedCnameTarget",
"cnameTarget",
"cnameMatchesExpected",
"asuidHost",
"asuidTxtRecords",
"commands",
"checks"
],
"additionalProperties": false
},
"description": "Configured or requested custom domains with diagnostics"
},
"manualSteps": {
"type": "array",
"items": {
"type": "string"
},
"description": "Provider-side manual setup steps"
},
"validationCommands": {
"type": "array",
"items": {
"type": "string"
},
"description": "Commands to validate DNS, Azure binding, TLS, and CORS after setup"
}
},
"required": [
"environment",
"platformApiHost",
"azure",
"domains",
"manualSteps",
"validationCommands"
],
"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/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)"
},
"centrifugo": {
"type": "object",
"description": "Centrifugo runtime status and version details",
"properties": {
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"disabled"
]
},
"ready": {
"type": "boolean"
},
"checkedAt": {
"type": "string"
},
"version": {
"type": "string"
},
"message": {
"type": "string"
},
"metrics": {
"type": "object",
"properties": {
"nodes": {
"type": "integer"
},
"channels": {
"type": "integer"
},
"clients": {
"type": "integer"
},
"users": {
"type": "integer"
},
"uptimeSeconds": {
"type": "integer"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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)"
}
}
}
},
"centrifugo": {
"type": "object",
"description": "Centrifugo runtime status and version details",
"properties": {
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"disabled"
]
},
"ready": {
"type": "boolean"
},
"checkedAt": {
"type": "string"
},
"version": {
"type": "string"
},
"message": {
"type": "string"
},
"metrics": {
"type": "object",
"properties": {
"nodes": {
"type": "integer"
},
"channels": {
"type": "integer"
},
"clients": {
"type": "integer"
},
"users": {
"type": "integer"
},
"uptimeSeconds": {
"type": "integer"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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 Chat
GET
/api/v1/system/chat/certificates
Get system chat certificate inventory
Return the shared certificate inventory and runtime binding status used by the Centrifugo Chat platform surfaces.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"provider",
"runtimeBindings",
"certificates",
"summary"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"letsencrypt",
"self-signed",
"none",
"aws-acm",
"kubernetes-cert-manager"
]
},
"runtimeBindings": {
"type": "array",
"items": {
"type": "object",
"required": [
"binding",
"endpoint",
"host",
"matchingDomainId",
"status"
],
"properties": {
"binding": {
"type": "string",
"enum": [
"chat-websocket",
"chat-http-api",
"chat-health"
]
},
"endpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"matchingDomainId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"matched",
"unmatched",
"unconfigured"
]
}
},
"additionalProperties": false
}
},
"certificates": {
"type": "array",
"items": {
"type": "object",
"required": [
"domainId",
"tenantId",
"domain",
"domainStatus",
"sslStatus",
"issuedAt",
"expiresAt",
"bindings"
],
"properties": {
"domainId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"domain": {
"type": "string"
},
"domainStatus": {
"type": "string",
"enum": [
"pending",
"verifying",
"verified",
"failed",
"expired"
]
},
"sslStatus": {
"type": "string",
"enum": [
"none",
"pending",
"issued",
"failed",
"expiring",
"expired"
]
},
"issuedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"bindings": {
"type": "array",
"items": {
"type": "string",
"enum": [
"chat-websocket",
"chat-http-api",
"chat-health"
]
}
}
},
"additionalProperties": false
}
},
"summary": {
"type": "object",
"required": [
"totalCertificates",
"issuedCertificates",
"pendingCertificates",
"expiringCertificates",
"expiredCertificates",
"failedCertificates"
],
"properties": {
"totalCertificates": {
"type": "integer",
"minimum": 0
},
"issuedCertificates": {
"type": "integer",
"minimum": 0
},
"pendingCertificates": {
"type": "integer",
"minimum": 0
},
"expiringCertificates": {
"type": "integer",
"minimum": 0
},
"expiredCertificates": {
"type": "integer",
"minimum": 0
},
"failedCertificates": {
"type": "integer",
"minimum": 0
}
},
"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
POST
/api/v1/system/chat/certificates/renew
Trigger system chat certificate renewal check
Run the shared certificate renewal and expiring-notification checks used by the Centrifugo Chat certificate operations surface.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"provider",
"renewedCertificates",
"expiringNotifications",
"triggeredAt"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"letsencrypt",
"self-signed",
"none",
"aws-acm",
"kubernetes-cert-manager"
]
},
"renewedCertificates": {
"type": "integer",
"minimum": 0
},
"expiringNotifications": {
"type": "integer",
"minimum": 0
},
"triggeredAt": {
"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
GET
/api/v1/system/chat/infrastructure
Get system chat infrastructure summary
Return the configured chat transport, HTTP API, and health endpoint infrastructure values visible to system administrators.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"runtimeEnabled",
"transportConfigured",
"httpApiConfigured",
"healthEndpointConfigured",
"wsEndpoint",
"httpApiEndpoint",
"internalHealthEndpoint",
"tokenIssuer",
"tokenAudience",
"useTls"
],
"properties": {
"runtimeEnabled": {
"type": "boolean"
},
"transportConfigured": {
"type": "boolean"
},
"httpApiConfigured": {
"type": "boolean"
},
"healthEndpointConfigured": {
"type": "boolean"
},
"wsEndpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"httpApiEndpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"internalHealthEndpoint": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tokenIssuer": {
"type": "string"
},
"tokenAudience": {
"type": "string"
},
"useTls": {
"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/chat/metrics
Get system chat metrics
Return cross-tenant conversation, message, delivery, and active runtime metrics for system chat diagnostics.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"conversationCount",
"participantCount",
"messagesLast24h",
"messagesLast7d",
"activeUsers",
"activeChannels",
"activePushDevices",
"queuedDeliveries",
"failedDeliveries",
"deliveredDeliveries",
"messageRateLimit",
"reconnectTelemetry",
"publishTelemetry"
],
"properties": {
"conversationCount": {
"type": "integer",
"minimum": 0
},
"participantCount": {
"type": "integer",
"minimum": 0
},
"messagesLast24h": {
"type": "integer",
"minimum": 0
},
"messagesLast7d": {
"type": "integer",
"minimum": 0
},
"activeUsers": {
"type": "integer",
"minimum": 0
},
"activeChannels": {
"type": "integer",
"minimum": 0
},
"activePushDevices": {
"type": "integer",
"minimum": 0
},
"queuedDeliveries": {
"type": "integer",
"minimum": 0
},
"failedDeliveries": {
"type": "integer",
"minimum": 0
},
"deliveredDeliveries": {
"type": "integer",
"minimum": 0
},
"messageRateLimit": {
"type": "object",
"required": [
"tenantsTracked",
"activeSends",
"sendsInWindow",
"rateLimitedCount",
"highestUtilizationPercent",
"tenantsNearLimit",
"lastMessageAt",
"lastRateLimitedAt"
],
"properties": {
"tenantsTracked": {
"type": "integer",
"minimum": 0
},
"activeSends": {
"type": "integer",
"minimum": 0
},
"sendsInWindow": {
"type": "integer",
"minimum": 0
},
"rateLimitedCount": {
"type": "integer",
"minimum": 0
},
"highestUtilizationPercent": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"tenantsNearLimit": {
"type": "integer",
"minimum": 0
},
"lastMessageAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastRateLimitedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"reconnectTelemetry": {
"type": "object",
"required": [
"windowMinutes",
"reconnectSessionCount",
"subscriptionBatchCount",
"lastReconnectAt",
"lastSubscriptionBatchAt"
],
"properties": {
"windowMinutes": {
"type": "integer",
"minimum": 1
},
"reconnectSessionCount": {
"type": "integer",
"minimum": 0
},
"subscriptionBatchCount": {
"type": "integer",
"minimum": 0
},
"lastReconnectAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastSubscriptionBatchAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"publishTelemetry": {
"type": "object",
"required": [
"windowMinutes",
"publishCount",
"publishFailureCount",
"averageLatencyMs",
"p95LatencyMs",
"lastPublishAt",
"lastPublishFailureAt"
],
"properties": {
"windowMinutes": {
"type": "integer",
"minimum": 1
},
"publishCount": {
"type": "integer",
"minimum": 0
},
"publishFailureCount": {
"type": "integer",
"minimum": 0
},
"averageLatencyMs": {
"type": "integer",
"minimum": 0
},
"p95LatencyMs": {
"type": "integer",
"minimum": 0
},
"lastPublishAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastPublishFailureAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"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/chat/policies
Get system chat policy summary
Return effective system-wide chat token TTL policy plus tenant override counts for routing and quiet-hours behavior.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"runtimeEnabled",
"connectionTokenTtlSeconds",
"subscriptionTokenTtlSeconds",
"tenantOverridesConfigured",
"managedRoutingTenants",
"disabledRoutingTenants",
"quietHoursEnabledTenants"
],
"properties": {
"runtimeEnabled": {
"type": "boolean"
},
"connectionTokenTtlSeconds": {
"type": "integer",
"minimum": 0
},
"subscriptionTokenTtlSeconds": {
"type": "integer",
"minimum": 0
},
"tenantOverridesConfigured": {
"type": "integer",
"minimum": 0
},
"managedRoutingTenants": {
"type": "integer",
"minimum": 0
},
"disabledRoutingTenants": {
"type": "integer",
"minimum": 0
},
"quietHoursEnabledTenants": {
"type": "integer",
"minimum": 0
}
},
"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/chat/push-deliveries
List system chat push deliveries
Return the cross-tenant push-delivery drill-down view with derived failure classification for system production support.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenantId",
"conversationId",
"recipientUserId",
"provider",
"status",
"failureClass",
"errorCode",
"errorMessage",
"suppressionReason",
"attemptCount",
"createdAt",
"sentAt",
"deliveredAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"conversationId": {
"type": "string",
"format": "uuid"
},
"recipientUserId": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"sending",
"sent",
"delivered",
"suppressed",
"failed"
]
},
"failureClass": {
"type": "string",
"enum": [
"none",
"suppressed",
"invalid-device",
"rate-limited",
"provider-auth",
"routing",
"transient",
"unknown"
]
},
"errorCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"errorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"suppressionReason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attemptCount": {
"type": "integer",
"minimum": 0
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"sentAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deliveredAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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/chat/push-providers
Get system chat push provider summary
Return the global push-provider governance summary separated from tenant chat policy surfaces.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"providers"
],
"properties": {
"providers": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"status",
"managedRoutingTenants",
"disabledRoutingTenants",
"quietHoursEnabledTenants",
"queuedDeliveryCount",
"failedDeliveryCount"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"managed"
]
},
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"disabled"
]
},
"managedRoutingTenants": {
"type": "integer",
"minimum": 0
},
"disabledRoutingTenants": {
"type": "integer",
"minimum": 0
},
"quietHoursEnabledTenants": {
"type": "integer",
"minimum": 0
},
"queuedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"failedDeliveryCount": {
"type": "integer",
"minimum": 0
}
},
"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/chat/push-runtime
Get system chat push runtime summary
Return cross-tenant push-device and push-delivery runtime diagnostics for system chat operations.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"activeDeviceCount",
"invalidDeviceCount",
"retiredDeviceCount",
"queuedDeliveryCount",
"failedDeliveryCount",
"suppressedDeliveryCount",
"deliveredDeliveryCount",
"lastQueuedDeliveryAt",
"lastFailedDeliveryAt"
],
"properties": {
"activeDeviceCount": {
"type": "integer",
"minimum": 0
},
"invalidDeviceCount": {
"type": "integer",
"minimum": 0
},
"retiredDeviceCount": {
"type": "integer",
"minimum": 0
},
"queuedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"failedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"suppressedDeliveryCount": {
"type": "integer",
"minimum": 0
},
"deliveredDeliveryCount": {
"type": "integer",
"minimum": 0
},
"lastQueuedDeliveryAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastFailedDeliveryAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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/system/chat/runtime
Get system chat runtime status
Return the effective Centrifugo runtime readiness, health endpoint status, and cluster node summary for system chat operations.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"runtimeEnabled",
"transportConfigured",
"httpApiConfigured",
"healthEndpointConfigured",
"healthStatus",
"healthHttpStatus",
"runtimeInfoStatus",
"runtimeInfoError",
"nodeCount",
"activeChannels",
"activeClients",
"activeUsers",
"version",
"reconnectTelemetry",
"publishTelemetry"
],
"properties": {
"runtimeEnabled": {
"type": "boolean"
},
"transportConfigured": {
"type": "boolean"
},
"httpApiConfigured": {
"type": "boolean"
},
"healthEndpointConfigured": {
"type": "boolean"
},
"healthStatus": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unavailable",
"not_configured"
]
},
"healthHttpStatus": {
"anyOf": [
{
"type": "integer",
"minimum": 100,
"maximum": 599
},
{
"type": "null"
}
]
},
"runtimeInfoStatus": {
"type": "string",
"enum": [
"available",
"unavailable"
]
},
"runtimeInfoError": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"nodeCount": {
"type": "integer",
"minimum": 0
},
"activeChannels": {
"type": "integer",
"minimum": 0
},
"activeClients": {
"type": "integer",
"minimum": 0
},
"activeUsers": {
"type": "integer",
"minimum": 0
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reconnectTelemetry": {
"type": "object",
"required": [
"windowMinutes",
"reconnectSessionCount",
"subscriptionBatchCount",
"lastReconnectAt",
"lastSubscriptionBatchAt"
],
"properties": {
"windowMinutes": {
"type": "integer",
"minimum": 1
},
"reconnectSessionCount": {
"type": "integer",
"minimum": 0
},
"subscriptionBatchCount": {
"type": "integer",
"minimum": 0
},
"lastReconnectAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastSubscriptionBatchAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"publishTelemetry": {
"type": "object",
"required": [
"windowMinutes",
"publishCount",
"publishFailureCount",
"averageLatencyMs",
"p95LatencyMs",
"lastPublishAt",
"lastPublishFailureAt"
],
"properties": {
"windowMinutes": {
"type": "integer",
"minimum": 1
},
"publishCount": {
"type": "integer",
"minimum": 0
},
"publishFailureCount": {
"type": "integer",
"minimum": 0
},
"averageLatencyMs": {
"type": "integer",
"minimum": 0
},
"p95LatencyMs": {
"type": "integer",
"minimum": 0
},
"lastPublishAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"lastPublishFailureAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"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/chat/scaling
Get system chat scaling status
Return Centrifugo node counts, active cluster totals, and token TTL settings used for system-level chat scaling decisions.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"nodeCount",
"activeChannels",
"activeClients",
"activeUsers",
"connectionTokenTtlSeconds",
"subscriptionTokenTtlSeconds",
"scalingMode",
"useTls"
],
"properties": {
"nodeCount": {
"type": "integer",
"minimum": 0
},
"activeChannels": {
"type": "integer",
"minimum": 0
},
"activeClients": {
"type": "integer",
"minimum": 0
},
"activeUsers": {
"type": "integer",
"minimum": 0
},
"connectionTokenTtlSeconds": {
"type": "integer",
"minimum": 0
},
"subscriptionTokenTtlSeconds": {
"type": "integer",
"minimum": 0
},
"scalingMode": {
"type": "string",
"enum": [
"single-node",
"clustered",
"unavailable"
]
},
"useTls": {
"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
System Notifications
GET
/api/v1/system/notifications/deliveries
List system notification deliveries
List cross-tenant notification deliveries for system-level diagnostics.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"userNotificationId",
"notificationEventId",
"tenantId",
"userId",
"channel",
"status",
"attemptCount",
"scheduledFor",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"userNotificationId": {
"type": "string",
"format": "uuid"
},
"notificationEventId": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"userId": {
"type": "string",
"format": "uuid"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"deviceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"sent",
"delivered",
"failed",
"suppressed",
"canceled",
"dead_letter"
]
},
"providerMessageId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"attemptCount": {
"type": "integer",
"minimum": 0
},
"lastErrorCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastErrorMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"scheduledFor": {
"type": "string",
"format": "date-time"
},
"processedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"nextCursor": {
"anyOf": [
{
"type": "string"
},
{
"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/system/notifications/deliveries/process
Process notification deliveries
Claim and process a bounded batch of due notification deliveries.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"tenantId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"claimedCount",
"processedCount",
"failedCount"
],
"properties": {
"claimedCount": {
"type": "integer",
"minimum": 0
},
"processedCount": {
"type": "integer",
"minimum": 0
},
"failedCount": {
"type": "integer",
"minimum": 0
}
},
"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/notifications/providers
Get notification provider health
Return system notification provider health for push routing diagnostics.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"channel",
"status",
"checkedAt"
],
"properties": {
"provider": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"down",
"unknown"
]
},
"checkedAt": {
"type": "string",
"format": "date-time"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"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/system/notifications/providers/test
Send notification provider test
Run a bounded provider diagnostic send against the configured notification provider surface.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"channel",
"recipient"
],
"properties": {
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"recipient": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"maxLength": 255
},
"body": {
"type": "string",
"maxLength": 4000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"accepted",
"channel",
"provider"
],
"properties": {
"accepted": {
"type": "boolean"
},
"channel": {
"type": "string",
"enum": [
"in_app",
"push",
"email",
"sms",
"whatsapp",
"webhook"
]
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"providerMessageId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"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/system/notifications/runtime
Get notification runtime
Return system notification queue and runtime health summary.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"required": [
"queuedOutboxCount",
"failedOutboxCount",
"nextScheduledOutboxAt"
],
"properties": {
"queuedOutboxCount": {
"type": "integer",
"minimum": 0
},
"failedOutboxCount": {
"type": "integer",
"minimum": 0
},
"nextScheduledOutboxAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"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
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 base-language fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Localized category summaries linked to the tag"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/tags/{id}
Update tag
Update tag base content, curated mode, and category assignments
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Base-language tag name"
},
"persistent": {
"type": "boolean",
"description": "Curated/persistent mode"
},
"category_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
}
}
}
📤 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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"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/taxonomy/tags/{id}/categories
Replace tag categories
Replace the category assignments of a tag
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"category_ids"
],
"properties": {
"category_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
}
}
}
📤 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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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-categories
Bulk modify tag categories
Add, remove, or clear categories for multiple tags
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_ids",
"action"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 100
},
"action": {
"type": "string",
"enum": [
"add",
"remove",
"clear"
]
},
"category_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50
}
}
}
📤 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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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)"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"language": {
"type": "string"
},
"sort_order": {
"type": "number"
}
},
"required": [
"id",
"key",
"name",
"language",
"sort_order"
],
"additionalProperties": false
},
"description": "Categories linked to the tag"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Additional-language name translations only; the base language stays in display_name and language"
},
"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",
"categories",
"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": {
"data": {
"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
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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": {
"data": {
"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
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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"
]
},
"user_name_format": {
"type": "string",
"enum": [
"first-middle-last",
"first-last",
"last-first",
"last-first-middle"
],
"description": "Tenant-specific ordering for generated user fullName values"
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format",
"user_name_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)"
},
"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
PATCH
/api/v1/secure/tenants/{id}/default-tenant-storage
Update tenant default storage
Update tenant default storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Must remain true for default tenant storage"
},
"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}/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
GET
/api/v1/secure/tenants/{id}/translation-coverage
Get translation coverage
Retrieve translation completeness across spaces, resources, categories, and tags for a tenant based on populated source fields versus configured additional tenant languages
📤 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 whose populated source fields are fully translated across all configured additional tenant languages"
},
"missing": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one missing translation for a populated source field in a configured additional tenant language"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Fully translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"missing",
"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 whose populated source fields are fully translated across all configured additional tenant languages"
},
"missing": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one missing translation for a populated source field in a configured additional tenant language"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Fully translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"missing",
"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 whose populated source fields are fully translated across all configured additional tenant languages"
},
"missing": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one missing translation for a populated source field in a configured additional tenant language"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Fully translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"missing",
"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 whose populated source fields are fully translated across all configured additional tenant languages"
},
"missing": {
"type": "integer",
"minimum": 0,
"description": "Entities with at least one missing translation for a populated source field in a configured additional tenant language"
},
"percentage": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"description": "Fully translated percentage rounded to a whole number"
}
},
"required": [
"total",
"translated",
"missing",
"percentage"
],
"additionalProperties": false
},
"missingItems": {
"type": "object",
"properties": {
"spaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"baseLanguage": {
"type": [
"null",
"string"
]
},
"missingLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"missingFieldsByLanguage": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"enum": [
"name",
"description"
]
}
}
}
},
"required": [
"id",
"title",
"description",
"baseLanguage",
"missingLanguages",
"missingFieldsByLanguage"
],
"additionalProperties": false
}
},
"resources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"baseLanguage": {
"type": [
"null",
"string"
]
},
"missingLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"missingFieldsByLanguage": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"enum": [
"name",
"description"
]
}
}
}
},
"required": [
"id",
"title",
"description",
"baseLanguage",
"missingLanguages",
"missingFieldsByLanguage"
],
"additionalProperties": false
}
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"baseLanguage": {
"type": [
"null",
"string"
]
},
"missingLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"missingFieldsByLanguage": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"enum": [
"name",
"description"
]
}
}
}
},
"required": [
"id",
"title",
"description",
"baseLanguage",
"missingLanguages",
"missingFieldsByLanguage"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"baseLanguage": {
"type": [
"null",
"string"
]
},
"missingLanguages": {
"type": "array",
"items": {
"type": "string"
}
},
"missingFieldsByLanguage": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"enum": [
"name",
"description"
]
}
}
}
},
"required": [
"id",
"title",
"description",
"baseLanguage",
"missingLanguages",
"missingFieldsByLanguage"
],
"additionalProperties": false
}
}
},
"required": [
"spaces",
"resources",
"categories",
"tags"
],
"additionalProperties": false
}
},
"required": [
"spaces",
"resources",
"categories",
"tags",
"missingItems"
],
"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": "Category hint used to infer appliesTo when appliesTo is omitted",
"maxLength": 100
},
"appliesTo": {
"type": "string",
"enum": [
"space",
"resource",
"calendar",
"user",
"tenant"
],
"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",
"tenant"
],
"description": "Entity type this definition applies to"
},
"schemaDefinition": {
"type": "object",
"description": "Canonical nested schema definition for the type",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"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",
"tenant"
],
"description": "Entity type this definition applies to"
},
"schemaDefinition": {
"type": "object",
"description": "Canonical nested schema definition for the type",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"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",
"tenant"
]
},
"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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"settings": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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
DELETE
/api/v1/secure/users/{id}
Delete user
Delete a user including auth, public profile, memberships, group links, and entity links.
📤 RESPONSE 204
User 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/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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"settings": {
"type": "object",
"additionalProperties": true
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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"
},
"tenantLinks": {
"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
},
"description": "All tenant memberships linked to this user account"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"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: ใจดี)"
},
"displayName": {
"type": "string",
"description": "Public display name. Never null; falls back to generated fullName."
},
"fullName": {
"type": "string",
"description": "Generated full name using tenant-specific name ordering."
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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
PATCH
/api/v1/secure/users/{id}/email-verification
Update email verification
Mark a user email verification task as verified or pending without relying on Supabase auth confirmation
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"verified": {
"type": "boolean"
}
},
"required": [
"verified"
],
"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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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
POST
/api/v1/secure/users/{id}/reset-password
Reset user password
Generate a temporary password for a user. The current password stops working immediately.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"generated",
"custom"
],
"default": "generated",
"description": "Whether to generate a temporary password or set a custom one directly"
},
"password": {
"anyOf": [
{
"type": "string",
"minLength": 8
},
{
"type": "null"
}
],
"description": "Required when mode is custom"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"generated",
"custom"
],
"description": "How the password reset was performed"
},
"message": {
"type": "string",
"description": "Operator-facing result summary"
},
"password": {
"anyOf": [
{
"type": "string",
"minLength": 8,
"description": "Temporary password returned once after a generated admin reset"
},
{
"type": "null"
}
]
}
},
"required": [
"mode",
"message",
"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
PATCH
/api/v1/secure/users/{id}/status
Update user status
Update the operational status for a specific user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
}
},
"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"
},
"tenantLinks": {
"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
}
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
],
"description": "User lifecycle status"
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"displayName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"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": "Default optimized delivery URL selected by entity media mapping rules."
},
"original_url": {
"type": "string",
"format": "uri",
"description": "Explicit signed URL for the original/current media bytes."
},
"current_version": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"description": "Newest stored media version. Clients must use GET /api/v1/services/media/:id/version for cache-safe image refresh checks."
},
"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",
"original_url",
"current_version",
"has_thumbnails"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"typeDefinitionId": {
"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",
"pattern": "^[a-z]{2}$",
"description": "User preferred locale. Must be one of the tenant languages from default_language plus additional_languages."
},
"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",
"tenantLinks",
"email",
"status",
"displayName",
"fullName",
"avatar_source",
"typeDefinitionId",
"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
DELETE
/api/v1/secure/users/{id}/tenants/{tenantId}
Remove user tenant link
Unlink a user from a selected tenant. System admins can target any tenant; tenant admins are limited to their active tenant.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success",
"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
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
}