Endpoints by Category
API Keys
GET
/api/v1/secure/api-keys/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"description": "Array of API key objects"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/api-keys/
No summary
Create a new API key with permission configuration. Returns the full key (only shown once!)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Human-readable name for the API key (1-100 chars)"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Optional description of key purpose (max 500 chars)"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n \"resources\": {\n \"read\": true,\n \"write\": true,\n \"delete\": false,\n \"properties\": [\"currentLocation\", \"status\"]\n },\n \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n```"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\", \"10.0.0.1\"])"
},
"device_fingerprint": {
"type": "string",
"description": "Optional device fingerprint for mobile attestation"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"fullKey": {
"type": "string",
"description": "CRITICAL: Full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"
},
"message": {
"type": "string",
"description": "Warning message to save the key securely"
}
},
"required": [
"data",
"fullKey",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/api-keys/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/api-keys/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Update API key name (1-100 chars)"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Update description (max 500 chars)"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Permission structure for programmatic access (app accounts & API keys).\n\n**Permission Templates:**\n- `READ_ONLY`: Read-only access to resources, spaces, and geo services\n- `ASSET_TRACKER`: Update resource location and status (for tracking apps)\n- `BOOKING_SYSTEM`: Full resource management with calendar access\n- `FULL_ACCESS`: Complete access to all services\n\n**Permission Sections:**\n- `resources`: Access to resource CRUD operations and specific properties\n- `spaces`: Access to space management\n- `geo`: Geocoding and reverse geocoding services\n- `calendar`: Calendar and availability services\n- `users`: User information access\n\n**Property-Level Access:**\nThe `resources.properties` array controls field-level access:\n- Empty array `[]` = Access to ALL properties\n- Specific list `[\"currentLocation\", \"status\"]` = Only these properties can be read/written\n\n**Example Usage:**\n```json\n{\n \"resources\": {\n \"read\": true,\n \"write\": true,\n \"delete\": false,\n \"properties\": [\"currentLocation\", \"status\"]\n },\n \"spaces\": { \"read\": true, \"write\": false, \"delete\": false },\n \"geo\": { \"geocode\": true, \"reverse_geocode\": true },\n \"calendar\": { \"free_busy\": false, \"events\": false },\n \"users\": { \"read\": false }\n}\n``` (partial update supported)"
},
"enabled": {
"type": "boolean",
"description": "Enable or disable the API key (false immediately revokes access)"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Update expiration timestamp (ISO 8601) or null to remove"
},
"ip_whitelist": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Update IP whitelist or null to remove restrictions"
},
"device_fingerprint": {
"type": [
"string",
"null"
],
"description": "Update device fingerprint or null to remove"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/api-keys/{id}
No summary
📤 RESPONSE 204
API key deleted successfully
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/api-keys/{id}/rotate
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "API key unique identifier"
},
"tenant_id": {
"type": "string",
"format": "uuid",
"description": "Tenant this key belongs to"
},
"key_uuid": {
"type": "string",
"format": "uuid",
"description": "Public part of the API key (shown in preview)"
},
"key_preview": {
"type": "string",
"description": "Obfuscated key preview (e.g., \"pve_sk_12345678...abcd\")"
},
"name": {
"type": "string",
"description": "Human-readable name for the API key"
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description of key purpose"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Fine-grained access permissions for programmatic access"
},
"enabled": {
"type": "boolean",
"description": "Whether the API key is currently active"
},
"expires_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Optional expiration timestamp (ISO 8601)"
},
"ip_whitelist": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Allowed IP addresses or CIDR ranges (e.g., [\"192.168.1.0/24\"])"
},
"device_fingerprint": {
"type": [
"null",
"string"
],
"description": "Optional device fingerprint for mobile attestation"
},
"last_used_at": {
"type": [
"null",
"string"
],
"format": "date-time",
"description": "Timestamp of last successful authentication (ISO 8601)"
},
"last_used_ip": {
"type": [
"null",
"string"
],
"description": "IP address of last successful authentication"
},
"request_count": {
"type": "integer",
"description": "Total number of requests made with this key"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid",
"description": "User who created this key"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp (ISO 8601)"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp (ISO 8601)"
}
},
"required": [
"id",
"tenant_id",
"key_uuid",
"key_preview",
"name",
"permissions",
"enabled",
"request_count",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"fullKey": {
"type": "string",
"description": "CRITICAL: New full API key (pve_sk_{uuid}_{secret}). Save immediately - shown only once!"
},
"message": {
"type": "string",
"description": "Warning message to save the new key securely"
}
},
"required": [
"data",
"fullKey",
"message"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Admin
GET
/api/v1/system/security/config
Get global security configuration
Returns platform-wide security settings (DOS, rate limiting, cache, circuit breaker). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/config
Update global security configuration
Update platform-wide security settings. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"dos_time_window_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"dos_block_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 86400
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number",
"minimum": 100,
"maximum": 50000
},
"queue_timeout_ms": {
"type": "number",
"minimum": 1000,
"maximum": 120000
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number",
"minimum": 3,
"maximum": 100
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number",
"minimum": 300,
"maximum": 604800
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number",
"minimum": 50,
"maximum": 99
},
"circuit_breaker_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"circuit_breaker_check_interval_seconds": {
"type": "number",
"minimum": 5,
"maximum": 60
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"cache_default_ttl_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist
List IP blacklist entries
Returns all blocked IP addresses. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/security/ip-blacklist
Block an IP address
Add an IP address to the blacklist. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ip_address"
],
"properties": {
"ip_address": {
"type": "string",
"description": "IPv4 or IPv6 address"
},
"reason": {
"type": "string",
"maxLength": 255,
"description": "Reason for blocking"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Expiration time (null = permanent)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist/{id}
Get IP blacklist entry
Get details of a specific blocked IP. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/ip-blacklist/{id}
Update IP blacklist entry
Update reason or expiration of a blocked IP. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 255
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/security/ip-blacklist/{id}
Unblock an IP address
Remove an IP address from the blacklist. System admin only.
📤 RESPONSE 204
No content
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/events
List security events
Returns security audit log entries. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"ip_address": {
"type": "string",
"nullable": true
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/metrics
Get security metrics
Returns aggregated security metrics (blocked IPs, events, etc.). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_blocked_ips": {
"type": "number"
},
"active_blocked_ips": {
"type": "number"
},
"permanent_blocks": {
"type": "number"
},
"temporary_blocks": {
"type": "number"
},
"auto_blocked_count": {
"type": "number"
},
"events_last_24h": {
"type": "number"
},
"events_by_type": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"events_by_severity": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/system/stats
No summary
Get system-wide storage statistics (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_tenants": {
"type": "number"
},
"enabled_tenants": {
"type": "number"
},
"total_quota_bytes": {
"type": "number"
},
"total_usage_bytes": {
"type": "number"
},
"average_usage_percent": {
"type": "number"
}
},
"required": [
"total_tenants",
"enabled_tenants",
"total_quota_bytes",
"total_usage_bytes",
"average_usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Application Accounts
GET
/api/v1/secure/app-accounts/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/
No summary
Create a new app account with optional permission configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"email",
"password"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"maxLength": 500
},
"password": {
"type": "string",
"minLength": 12,
"description": "Minimum 12 characters"
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
},
"description": "Optional permission configuration for this app account"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/app-accounts/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/app-accounts/{id}
No summary
Update app account details including permissions
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"auth_user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"description": {
"type": "string",
"nullable": true
},
"permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"resources": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed property names. Empty array = all properties accessible"
}
}
},
"spaces": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
}
}
},
"geo": {
"type": "object",
"additionalProperties": false,
"properties": {
"geocode": {
"type": "boolean"
},
"reverse_geocode": {
"type": "boolean"
}
}
},
"calendar": {
"type": "object",
"additionalProperties": false,
"properties": {
"free_busy": {
"type": "boolean"
},
"events": {
"type": "boolean"
}
}
},
"users": {
"type": "object",
"additionalProperties": false,
"properties": {
"read": {
"type": "boolean"
}
}
}
}
},
"status": {
"type": "string",
"enum": [
"active",
"suspended",
"revoked"
]
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"email",
"permissions",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/app-accounts/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/{id}/regenerate-password
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/app-accounts/{id}/set-password
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
},
"message": {
"type": "string"
}
},
"required": [
"data"
],
"additionalProperties": true
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/app-accounts/{id}/usage-stats
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
],
"additionalProperties": true
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Audit Logs
GET
/api/v1/secure/audit-logs/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"action": {
"type": "string"
},
"resource_type": {
"type": "string"
},
"resource_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"details": {
"type": "object",
"additionalProperties": true,
"nullable": true
},
"ip_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user_agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"action",
"resource_type",
"created_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Auth
POST
/api/v1/public/auth/login
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"rememberMe": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"displayName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"tenantName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"groupDetails": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"permissions"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"permissions": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"isSystemAdmin": {
"type": "boolean"
},
"isTenantAdmin": {
"type": "boolean"
}
},
"required": [
"id",
"email",
"tenantId",
"groups",
"isSystemAdmin",
"isTenantAdmin"
],
"additionalProperties": false
},
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"expiresIn": {
"type": "number"
}
},
"required": [
"user",
"accessToken",
"refreshToken",
"expiresIn"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/register
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password",
"tenantName",
"tenantDomain"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"tenantName": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"tenantDomain": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 63
},
"displayName": {
"type": "string",
"maxLength": 255
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"tenantId": {
"type": "string"
}
}
},
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"domain": {
"type": "string"
}
}
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/refresh
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"refreshToken": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"accessToken": {
"type": "string"
},
"refreshToken": {
"type": "string"
},
"expiresIn": {
"type": "number"
}
},
"required": [
"accessToken",
"refreshToken",
"expiresIn"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/public/auth/logout
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/auth/me
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"displayName": {
"type": "string"
},
"locale": {
"type": "string"
}
},
"required": [
"id",
"email",
"tenantId"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Calendar
GET
/api/v1/secure/calendar/
No summary
📤 RESPONSE 200
Default Response
Categories
GET
/api/v1/secure/taxonomy/categories/
No summary
List categories with optional filters (flat listing)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/
No summary
Create category (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"key",
"translations"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 1,
"maxLength": 100
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"filter_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100
},
"translations": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/tree
No summary
Get category tree (hierarchical listing)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"children": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Recursive category structure"
},
"description": "Child categories (hierarchical)"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/{id}
No summary
Get category by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/categories/{id}
No summary
Update category (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 1,
"maxLength": 100
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"filter_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Parent category ID (null for root)"
},
"key": {
"type": "string",
"description": "URL-safe identifier"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional filter for type-specific categories"
},
"level": {
"type": "number",
"description": "Hierarchy depth (0 = root)"
},
"name": {
"type": "string",
"description": "Display name in base language"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description in base language"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this category"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"translations_i18n",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}
No summary
Delete category (admin only, requires replacement if links exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"replacement_category_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Category deleted successfully
Schema: Category deleted successfully
{
"description": "Category deleted successfully",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deleted": {
"type": "boolean"
},
"relinked_count": {
"type": "number"
},
"replacement_category_id": {
"type": [
"null",
"string"
]
}
}
}
}
}
PATCH
/api/v1/secure/taxonomy/categories/{id}/i18n
No summary
Upsert category translation (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"locale",
"name"
],
"properties": {
"locale": {
"type": "string",
"enum": [
"de",
"en",
"fr",
"it"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"locale": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"locale",
"name",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/categories/{id}/link
No summary
Link category to entity
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/categories/{id}/unlink
No summary
Unlink category from entity
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Category unlinked successfully
GET
/api/v1/secure/taxonomy/categories/entity
No summary
Get all categories for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/categories/{id}/entities
No summary
Get all entities with this category (reverse lookup filter)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
Contacts
GET
/api/v1/secure/contacts/
No summary
List contacts with optional filters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/contacts/
No summary
Create a new contact
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"firstName": {
"type": "string",
"maxLength": 100,
"description": "Passport first name (romanized)"
},
"middleName": {
"type": "string",
"maxLength": 100,
"description": "Passport middle name (optional)"
},
"lastName": {
"type": "string",
"maxLength": 100,
"description": "Passport last name (romanized)"
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string",
"maxLength": 50
},
"url": {
"type": "string",
"format": "uri"
},
"address": {
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
"notes": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/contacts/{id}
No summary
Get a contact by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/contacts/{id}
No summary
Update a contact
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"firstName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport first name (romanized)"
},
"middleName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport middle name (optional)"
},
"lastName": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Passport last name (romanized)"
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
]
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 50
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/contacts/{id}
No summary
Delete a contact
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/contacts/{id}/references
No summary
Get all entities (users, spaces, resources) linked to a contact
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_name": {
"type": "string"
},
"entity_description": {
"type": [
"null",
"string"
]
},
"entity_status": {
"type": [
"null",
"string"
]
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"entity_type",
"entity_id",
"entity_name",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/contacts
No summary
Get contacts linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/contacts
No summary
Link a contact to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/contacts/{contactId}
No summary
Unlink a contact from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/contacts
No summary
Get contacts linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/contacts
No summary
Link a contact to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/contacts/{contactId}
No summary
Unlink a contact from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/contacts
No summary
Get contacts linked to a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/{id}/contacts
No summary
Link a contact to a user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/users/{id}/contacts/{contactId}
No summary
Unlink a contact from a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Countries (Public)
GET
/api/v1/public/countries/
List all countries with optional filters and prioritization
Get all countries with optional search, region filter, localization, and prioritized sorting. Priority countries appear first, followed by alphabetically sorted remaining countries. No tenant isolation - same data for all tenants.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"name_ascii": {
"type": "string",
"description": "International country name in English (ASCII-safe)",
"example": "Switzerland"
},
"name_local": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Localized country names per language code",
"example": {
"de": "Schweiz",
"fr": "Suisse",
"it": "Svizzera",
"rm": "Svizra"
}
},
"flag_url": {
"type": "string",
"format": "uri",
"description": "Flag image URL from FlagsAPI.com",
"example": "https://flagsapi.com/CH/flat/64.png"
},
"metadata": {
"type": "object",
"properties": {
"region": {
"type": "string",
"example": "Europe"
},
"calling_code": {
"type": "string",
"example": "+41"
},
"currency_code": {
"type": "string",
"example": "CHF"
},
"capital": {
"type": "string",
"example": "Bern"
}
},
"additionalProperties": true,
"description": "Additional metadata (region, calling code, currency, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was last updated"
},
"name": {
"type": "string",
"description": "Localized name based on language query parameter (computed field)",
"example": "Schweiz"
}
},
"required": [
"iso_code",
"name_ascii",
"name_local",
"flag_url",
"metadata",
"created_at",
"updated_at",
"name"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of countries matching filters"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"description": "Number of countries per page"
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "Number of countries skipped"
}
},
"required": [
"countries",
"total",
"limit",
"offset"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
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
}
GET
/api/v1/public/countries/{isoCode}
Get country by ISO code
Get single country by ISO 3166-1 alpha-2 code (e.g., CH, DE, TH). Returns localized name based on language parameter or Accept-Language header.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"iso_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 country code (2 uppercase letters)",
"example": "CH"
},
"name_ascii": {
"type": "string",
"description": "International country name in English (ASCII-safe)",
"example": "Switzerland"
},
"name_local": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Localized country names per language code",
"example": {
"de": "Schweiz",
"fr": "Suisse",
"it": "Svizzera",
"rm": "Svizra"
}
},
"flag_url": {
"type": "string",
"format": "uri",
"description": "Flag image URL from FlagsAPI.com",
"example": "https://flagsapi.com/CH/flat/64.png"
},
"metadata": {
"type": "object",
"properties": {
"region": {
"type": "string",
"example": "Europe"
},
"calling_code": {
"type": "string",
"example": "+41"
},
"currency_code": {
"type": "string",
"example": "CHF"
},
"capital": {
"type": "string",
"example": "Bern"
}
},
"additionalProperties": true,
"description": "Additional metadata (region, calling code, currency, etc.)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was added"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp when country was last updated"
},
"name": {
"type": "string",
"description": "Localized name based on language query parameter (computed field)",
"example": "Schweiz"
}
},
"required": [
"iso_code",
"name_ascii",
"name_local",
"flag_url",
"metadata",
"created_at",
"updated_at",
"name"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
Features
GET
/api/v1/secure/features/
No summary
List all features for current tenant with their status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/{key}
No summary
Get status of a specific feature
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/features/{key}
No summary
Enable or disable a feature (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether to enable or disable the feature"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Feature-specific configuration"
},
"changed_reason": {
"type": "string",
"description": "Reason for the change (audit trail)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/features/bulk
No summary
Bulk enable/disable features (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"updates"
],
"properties": {
"updates": {
"type": "array",
"items": {
"type": "object",
"required": [
"feature_key",
"enabled"
],
"properties": {
"feature_key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"changed_reason": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"feature_key": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"definition": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/catalog
No summary
Get catalog of all available features (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Feedback
POST
/api/v1/secure/feedback/rating
No summary
Submit a rating for an entity (resource, space, booking, app)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entityType",
"entityId",
"ratingType",
"value"
],
"properties": {
"entityType": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entityId": {
"type": "string",
"format": "uuid"
},
"ratingType": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 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
PUT
/api/v1/secure/feedback/rating/{id}
No summary
Update an existing rating
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"value": {
"type": "number"
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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/feedback/review
No summary
Submit a review linked to a rating
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ratingId",
"content"
],
"properties": {
"ratingId": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string",
"minLength": 10,
"maxLength": 5000
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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}
No summary
Update an existing review
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 10,
"maxLength": 5000
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"isPublic": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default 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/feedback/review/{id}/flag
No summary
Flag a review for moderation (admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"reason"
],
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/feedback/{entityType}/{entityId}/ratings
No summary
Get all ratings for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"value": {
"type": "number"
},
"is_public": {
"type": "boolean"
},
"user_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user_avatar": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"user_id",
"entity_type",
"entity_id",
"rating_type",
"value",
"is_public",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/feedback/{entityType}/{entityId}/reviews
No summary
Get all reviews for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"rating_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"content": {
"type": "string"
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"format": "uuid"
},
"media_type": {
"type": "string",
"enum": [
"image",
"video",
"document"
]
},
"url": {
"type": "string",
"format": "uri"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"media_id",
"media_type",
"url"
],
"additionalProperties": false
}
},
"is_public": {
"type": "boolean"
},
"is_flagged": {
"type": "boolean"
},
"flagged_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"flagged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"flagged_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"user_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"user_avatar": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"rating_id",
"user_id",
"content",
"attachments",
"is_public",
"is_flagged",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/feedback/{entityType}/{entityId}/aggregates
No summary
Get rating aggregates (average, count, distribution) for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entity_type": {
"type": "string",
"enum": [
"app",
"booking",
"resource",
"space"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"rating_type": {
"type": "string",
"enum": [
"hearts",
"stars"
]
},
"total_count": {
"type": "number"
},
"average_rating": {
"type": "number"
},
"distribution": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Rating value -> count mapping"
},
"public_count": {
"type": "number"
},
"private_count": {
"type": "number"
}
},
"required": [
"entity_type",
"entity_id",
"rating_type",
"total_count",
"average_rating",
"distribution",
"public_count",
"private_count"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- 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
Files
POST
/api/v1/secure/files/upload
No summary
Upload file with intelligent storage distribution
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"fileId": {
"type": "string",
"format": "uuid"
},
"providerId": {
"type": "string",
"format": "uuid"
},
"providerPath": {
"type": "string"
},
"publicUrl": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string"
}
},
"required": [
"fileId",
"providerId",
"providerPath",
"publicUrl",
"sizeBytes"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/search
No summary
Search files with filters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string",
"nullable": true
},
"sizeBytes": {
"type": "number"
},
"spaceId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"providerId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"providerName": {
"type": "string"
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/statistics
No summary
Get file statistics for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"totalFiles": {
"type": "number"
},
"totalSizeBytes": {
"type": "number"
},
"byContentType": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"additionalProperties": false
}
},
"byProvider": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"sizeBytes": {
"type": "number"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/{fileId}/download
No summary
Download file by ID
📤 RESPONSE 200
Inline Schema
Response: File stream
Schema: File stream
{
"type": "string",
"format": "binary",
"description": "File stream"
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/{fileId}
No summary
Get file metadata
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"providerId": {
"type": "string",
"format": "uuid"
},
"providerPath": {
"type": "string"
},
"originalFilename": {
"type": "string"
},
"contentType": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"resourceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"uploadedAt": {
"type": "string",
"format": "date-time"
},
"movedCount": {
"type": "number"
},
"lastMovedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"metadata": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/{fileId}
No summary
Delete file
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/{fileId}/move
No summary
Move file to different storage provider
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"targetProviderId"
],
"properties": {
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/
No summary
Create a bulk file migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"fileIds",
"targetProviderId"
],
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "File IDs to migrate"
},
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/
No summary
List file migration jobs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/{jobId}
No summary
Get migration job details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/migrations/{jobId}
No summary
Cancel a migration job
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/{jobId}/start
No summary
Start processing a migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Maximum concurrent file migrations"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Geo-Location
POST
/api/v1/secure/geo/geocode
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"anyOf": [
{
"required": [
"address"
]
},
{
"required": [
"structured"
]
}
],
"properties": {
"address": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"structured": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"formatted_address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"country_code": {
"type": "string"
}
}
},
"display_name": {
"type": "string"
},
"confidence": {
"type": "number"
},
"provider": {
"type": "string"
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/geo/reverse
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"zoom": {
"type": "number",
"minimum": 1,
"maximum": 18
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"formatted_address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"house_number": {
"type": "string"
},
"city": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
},
"country": {
"type": "string"
},
"country_code": {
"type": "string"
}
}
},
"display_name": {
"type": "string"
},
"provider": {
"type": "string"
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/autocomplete
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"suggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"display_name": {
"type": "string"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"type": {
"type": "string"
},
"importance": {
"type": "number"
}
}
}
},
"cached": {
"type": "boolean"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/config
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/geo/config
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"locale",
"format_type",
"address_template",
"component_order"
],
"properties": {
"locale": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string",
"minLength": 1
},
"component_order": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"separator": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/geo/config
Delete geo display config
Delete a display configuration for the current tenant
📤 RESPONSE 204
Successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/geo/configs
Get batch geo configs
Get display configurations for multiple locales in one call
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"locale": {
"type": "string"
},
"format_type": {
"type": "string",
"enum": [
"local",
"international"
]
},
"address_template": {
"type": "string"
},
"component_order": {
"type": "array",
"items": {
"type": "string"
}
},
"separator": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"tenant_id",
"locale",
"format_type",
"address_template",
"component_order",
"separator",
"created_at",
"updated_at"
]
},
"description": "Map of locale codes to config objects"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Group Members
POST
/api/v1/secure/groups/{id}/members
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/groups/{id}/members
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/groups/{id}/members/{userId}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Groups
GET
/api/v1/secure/groups/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/groups/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PUT
/api/v1/secure/groups/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/groups/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/groups/create
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Group description"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permission codes"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"permissions",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Jobs
GET
/api/v1/secure/jobs/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"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"
}
},
"required": [
"name",
"enabled",
"isSystem"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/{name}/status
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"lastRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"nextRun": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"isSystem": {
"type": "boolean"
},
"runCount": {
"type": "number"
},
"successCount": {
"type": "number"
},
"failureCount": {
"type": "number"
},
"avgDurationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/active
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
},
"jobName": {
"type": "string"
},
"tenantId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"startedAt": {
"type": "string"
},
"correlationId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"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/jobs/{name}/history
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"jobName": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"success",
"failure",
"running",
"cancelled"
]
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenantId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"page": {
"type": "number"
},
"pageSize": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/history
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"jobName": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"success",
"failure",
"running",
"cancelled"
]
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tenantId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"page": {
"type": "number"
},
"pageSize": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/jobs/{name}/trigger
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
},
"tenantId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobId": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/jobs/{name}/{jobId}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"cancelled": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/jobs/{name}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/jobs/notifications/settings
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"emailRecipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"notifyOnSuccess": {
"type": "boolean"
},
"notifyOnFailure": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/jobs/notifications/settings
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"jobName"
],
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"notify_on_failure": {
"type": "boolean"
},
"notify_on_completion": {
"type": "boolean"
},
"notify_on_long_running": {
"type": "boolean"
},
"long_running_threshold_ms": {
"type": "number"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobName": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"emailRecipients": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"notifyOnSuccess": {
"type": "boolean"
},
"notifyOnFailure": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Languages (Public)
GET
/api/v1/public/languages/
List all languages with optional filters and prioritization
Get all languages with optional search, prioritization, and country-specific filtering.
**Prioritization Logic:**
- Default priority languages: de, fr, it, es (shown first)
- If countryCode provided: adds country-specific languages + en to top
- Example: ?countryCode=CH → de,fr,it,rm,en appear first
**Supported Country Codes:** CH, DE, FR, IT, ES, US, GB, TH, JP, CN, KR
No tenant isolation - same data for all tenants.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"languages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"iso_code_1": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "ISO 639-1 two-letter language code (lowercase)",
"example": "en"
},
"iso_code_2": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-2 three-letter language code (lowercase)",
"example": "eng"
},
"iso_code_3": {
"type": "string",
"pattern": "^[a-z]{3}$",
"nullable": true,
"description": "ISO 639-3 three-letter language code (lowercase, alternative)",
"example": "eng"
},
"name_english": {
"type": "string",
"description": "English name of the language (international standard)",
"example": "English"
},
"name_local": {
"type": "string",
"description": "Native name in language's own script (UTF-8)",
"example": "English"
},
"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"
]
}
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"
},
"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"
]
}
Lifecycle
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/activate
No summary
Activate tenant (pending → trial, or inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for activation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/upgrade
No summary
Upgrade tenant type (trial → paid → enterprise)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"target_type"
],
"properties": {
"target_type": {
"type": "string",
"enum": [
"paid",
"enterprise"
],
"description": "Target plan type"
},
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for upgrade (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/suspend
No summary
Suspend tenant (active → inactive)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for suspension (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/reactivate
No summary
Reactivate tenant (inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for reactivation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/archive
No summary
Archive tenant (inactive → retired)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for archiving (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/lifecycle/{id}/history
No summary
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"from_status": {
"type": "string"
},
"to_status": {
"type": "string"
},
"from_type": {
"type": "string"
},
"to_type": {
"type": "string"
},
"action": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"performed_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"from_status",
"to_status",
"action",
"performed_by",
"created_at"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Media
POST
/api/v1/services/media/upload
No summary
Upload media file with multipart/form-data
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
GET
/api/v1/services/media/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
]
}
GET
/api/v1/services/media/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
DELETE
/api/v1/services/media/{id}
No summary
📤 RESPONSE 204
Media file deleted successfully
GET
/api/v1/services/media/{id}/versions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"media_file_id",
"version",
"storage_path",
"public_url",
"file_size_bytes",
"mime_type",
"uploaded_at",
"uploaded_by",
"metadata"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"mime_type": {
"type": "string"
},
"uploaded_at": {
"type": "string",
"format": "date-time"
},
"uploaded_by": {
"type": "string",
"format": "uuid"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "File metadata (EXIF, dimensions, etc.)"
}
}
}
}
},
"required": [
"data"
]
}
POST
/api/v1/services/media/{id}/geo-tag
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"required": [
"data"
]
}
POST
/api/v1/services/media/{id}/thumbnails/regenerate
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"version": {
"type": "number",
"minimum": 1
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"thumbnails": {
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"media_file_id",
"version",
"thumbnails"
]
}
},
"required": [
"data"
]
}
GET
/api/v1/services/media/{id}/thumbnails
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "number",
"minimum": 1
},
"thumbnails": {
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"media_file_id",
"version",
"thumbnails"
]
}
},
"required": [
"data"
]
}
POST
/api/v1/services/media/entity/{entityType}/{entityId}/media
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"media_file_id"
],
"properties": {
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number",
"minimum": 0
},
"public_display": {
"type": "boolean"
},
"display_from": {
"type": "string",
"format": "date-time"
},
"display_until": {
"type": "string",
"format": "date-time"
},
"caption": {
"type": "string",
"maxLength": 1000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
GET
/api/v1/services/media/entity/{entityType}/{entityId}/media
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
},
"required": [
"data"
]
}
GET
/api/v1/services/media/entity/{entityType}/{entityId}/media/main
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
]
}
},
"required": [
"data"
]
}
PUT
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number",
"minimum": 0
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
DELETE
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}
No summary
📤 RESPONSE 204
Media unlinked successfully
PATCH
/api/v1/services/media/entity/{entityType}/{entityId}/media/{linkId}/main
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by",
"media"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
},
"media": {
"type": "object",
"required": [
"id",
"tenant_id",
"user_id",
"file_type",
"mime_type",
"file_size_bytes",
"storage_path",
"public_url",
"current_version",
"original_filename",
"create_thumbnails",
"has_thumbnails",
"exif_stripped",
"metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"file_type": {
"type": "string",
"enum": [
"avatar",
"profile_picture",
"document",
"image",
"video",
"other"
]
},
"mime_type": {
"type": "string"
},
"file_size_bytes": {
"type": "number",
"minimum": 0
},
"storage_path": {
"type": "string"
},
"public_url": {
"type": "string",
"format": "uri"
},
"current_version": {
"type": "number",
"minimum": 1
},
"original_filename": {
"type": "string",
"description": "Original filename for display"
},
"create_thumbnails": {
"type": "boolean",
"description": "Whether to generate thumbnails (user preference)"
},
"has_thumbnails": {
"type": "boolean",
"description": "Whether thumbnails were successfully generated"
},
"parent_media_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to previous version for version history"
},
"geo_location": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"latitude",
"longitude"
],
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"additionalProperties": false
}
]
},
"exif_stripped": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {
"original_filename": {
"type": "string"
},
"dimensions": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
]
},
"thumbnails": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"small": {
"type": "string",
"format": "uri"
},
"medium": {
"type": "string",
"format": "uri"
},
"large": {
"type": "string",
"format": "uri"
},
"preview": {
"type": "string",
"format": "uri"
}
}
}
]
},
"checksum": {
"type": "string"
},
"caption": {
"type": "string"
}
}
},
"tags": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Tags associated with this media file"
},
"categories": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"slug"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
}
}
}
],
"description": "Categories associated with this media file"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
},
"required": [
"data"
]
}
PUT
/api/v1/services/media/entity/{entityType}/{entityId}/media/reorder
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"reorder"
],
"properties": {
"reorder": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"sort_order"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"sort_order": {
"type": "number",
"minimum": 0
}
}
},
"minItems": 1
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"media_file_id",
"is_main",
"sort_order",
"public_display",
"created_at",
"created_by"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"tenant",
"space",
"resource",
"user",
"contact"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_display": {
"type": "boolean"
},
"display_from": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"display_until": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"caption": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"maxLength": 1000
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"required": [
"data"
]
}
Messaging
POST
/api/v1/services/messaging/send
No summary
Queue a message for delivery via email, SMS, WhatsApp, or webhook
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"channel"
],
"properties": {
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"recipient_email": {
"type": "string",
"format": "email"
},
"recipient_phone": {
"type": "string"
},
"recipient_user_id": {
"type": "string",
"format": "uuid"
},
"template_id": {
"type": "string",
"format": "uuid"
},
"template_name": {
"type": "string"
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"variables": {
"type": "object",
"additionalProperties": true,
"description": "Template variables for substitution"
}
}
}
📤 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"
}
}
}
}
}
GET
/api/v1/services/messaging/{id}/status
No summary
Get delivery status and tracking info for a specific message
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"channel": {
"type": "string"
},
"retry_count": {
"type": "number"
},
"last_error": {
"type": "string",
"nullable": 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
}
}
}
}
}
POST
/api/v1/services/messaging/preview
No summary
Preview a rendered message template with variables without sending it
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"template_id",
"variables"
],
"properties": {
"template_id": {
"type": "string",
"format": "uuid"
},
"variables": {
"type": "object"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"nullable": true
},
"content": {
"type": "string"
},
"variables_used": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
GET
/api/v1/services/messaging/templates
No summary
List available message templates, optionally filtered by channel
📤 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"
}
}
}
}
}
}
}
POST
/api/v1/services/messaging/templates
No summary
Create a new message template
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"channel",
"content",
"variables"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"channel": {
"type": "string",
"enum": [
"email",
"sms",
"whatsapp",
"webhook"
]
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 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"
}
}
}
}
}
}
GET
/api/v1/services/messaging/stats
No summary
Get messaging statistics for the tenant (counts by status)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_messages": {
"type": "number"
},
"queued": {
"type": "number"
},
"sent": {
"type": "number"
},
"delivered": {
"type": "number"
},
"failed": {
"type": "number"
},
"bounced": {
"type": "number"
}
}
}
}
}
GET
/api/v1/services/messaging/recent
No summary
List recent messages sent by the tenant with optional limit
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"channel": {
"type": "string"
},
"status": {
"type": "string"
},
"subject": {
"type": "string",
"nullable": true
},
"recipient_email": {
"type": "string",
"nullable": true
},
"recipient_phone": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string"
},
"sent_at": {
"type": "string",
"nullable": true
}
}
}
}
}
}
PUT
/api/v1/services/messaging/templates/{id}
No summary
Update a message template (creates new version)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"description": {
"type": "string"
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"channel": {
"type": "string"
},
"version": {
"type": "number"
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
DELETE
/api/v1/services/messaging/templates/{id}
No summary
Delete a message template (deactivates all versions)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
Migration
POST
/api/v1/secure/files/migrations/
No summary
Create a bulk file migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"fileIds",
"targetProviderId"
],
"properties": {
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"maxItems": 1000,
"description": "File IDs to migrate"
},
"targetProviderId": {
"type": "string",
"format": "uuid",
"description": "Target storage provider ID"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/
No summary
List file migration jobs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/files/migrations/{jobId}
No summary
Get migration job details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenantId": {
"type": "string",
"format": "uuid"
},
"fileIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"targetProviderId": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdBy": {
"type": "string",
"format": "uuid"
},
"error": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/files/migrations/{jobId}
No summary
Cancel a migration job
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/files/migrations/{jobId}/start
No summary
Start processing a migration job
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5,
"description": "Maximum concurrent file migrations"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"progress": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"completed": {
"type": "number"
},
"failed": {
"type": "number"
},
"currentFileId": {
"type": "string",
"nullable": true
},
"percent": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Phone Validation (Public)
POST
/api/v1/public/phone/validate
Validate phone number
Validate phone number format and return detailed information if valid
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41 79 123 45 67)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
POST
/api/v1/public/phone/format
Format phone number
Format phone number in specified format
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41791234567)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
},
"format": {
"type": "string",
"enum": [
"E.164",
"INTERNATIONAL",
"NATIONAL",
"RFC3966"
],
"default": "E.164"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
POST
/api/v1/public/phone/parse
Parse phone number
Parse phone number to extract components
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"phone"
],
"properties": {
"phone": {
"type": "string",
"description": "Phone number (e.g., +41 79 123 45 67)"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO country code (e.g., CH)"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
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",
"additionalProperties": true
}
}
}
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",
"additionalProperties": true
}
}
}
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",
"additionalProperties": true
}
}
}
Resource Move Requests
POST
/api/v1/secure/resources/{id}/move
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"targetSpaceId"
],
"properties": {
"targetSpaceId": {
"type": "string",
"format": "uuid"
},
"reason": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/resource-requests
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/resource-requests/{id}/approve
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/resource-requests/{id}/reject
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"rejectionReason"
],
"properties": {
"rejectionReason": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"reason": {
"type": [
"null",
"string"
]
},
"rejection_reason": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"completed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/resource-requests/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"source_space_id": {
"type": "string",
"format": "uuid"
},
"target_space_id": {
"type": "string",
"format": "uuid"
},
"requested_by": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"requires_resource_approval": {
"type": "boolean"
},
"approved_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"reason": {
"type": [
"null",
"string"
]
},
"rejection_reason": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"processed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"completed_at": {
"type": [
"null",
"string"
],
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"resource_id",
"source_space_id",
"target_space_id",
"requested_by",
"status",
"requires_resource_approval",
"created_at",
"expires_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Resource Owners
GET
/api/v1/secure/resources/{id}/owners
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "uuid"
},
"email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
]
},
"created_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"user_id"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/owners
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string",
"format": "email"
}
},
"userIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "null"
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/owners/{userId}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "null"
}
},
"required": [
"data"
]
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Resources
GET
/api/v1/secure/resources/
No summary
List all resources in tenant with filtering and pagination
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"spaceId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"resourceType": {
"type": "string",
"enum": [
"system",
"custom"
],
"description": "Use for management only (system, custom) - defaults to custom"
},
"typeDefinition": {
"type": "string",
"description": "Schema type name or UUID for settings validation (can be UUID or name of type_definition)"
},
"description": {
"type": "string",
"maxLength": 2000
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Custom settings validated against type_definition schema"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"retired"
]
},
"currentLocation": {
"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
}
]
},
"tagIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Tag IDs to link to this resource",
"nullable": true
},
"categoryIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Category IDs to link to this resource",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/resources/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"resourceType": {
"type": "string",
"enum": [
"system",
"custom"
],
"description": "Use for management only (system, custom) - Cannot be changed after creation"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Custom settings validated against type_definition schema"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"currentLocation": {
"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
}
]
},
"tagIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Tag IDs to link to this resource",
"nullable": true
},
"categoryIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Category IDs to link to this resource",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}
No summary
📤 RESPONSE 204
Default Response
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/detach
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this resource"
},
"current_space_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"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": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Resource-specific settings and metadata"
},
"currentLocation": {
"anyOf": [
{
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Geographic coordinates (latitude/longitude) of resource location"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"status",
"typeName",
"typeDefinitionId",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/tags
No summary
Get all tags linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/tags
No summary
Link a tag to a resource (creates tag if it doesn't exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name (will be normalized)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/tags/{tagId}
No summary
Unlink a tag from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/categories
No summary
Get all categories linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/categories
No summary
Link a category to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"category_id"
],
"properties": {
"category_id": {
"type": "string",
"format": "uuid",
"description": "Category UUID"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/categories/{categoryId}
No summary
Unlink a category from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/resources/{id}/contacts
No summary
Get contacts linked to a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/resources/{id}/contacts
No summary
Link a contact to a resource
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/resources/{id}/contacts/{contactId}
No summary
Unlink a contact from a resource
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
S3
GET
/api/v1/secure/storage/s3/
No summary
List all S3 storage configurations for the current tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/storage/s3/
No summary
Create a new S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"region",
"bucket_name",
"access_key_id",
"secret_access_key"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"region": {
"type": "string",
"minLength": 1
},
"bucket_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpoint_url": {
"type": "string",
"maxLength": 500
},
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"fallback_region": {
"type": "string"
},
"fallback_bucket": {
"type": "string"
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": "string"
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": "string"
},
"cdn_domain": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/regions
No summary
Get available AWS S3 regions
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/encryption-types
No summary
Get available S3 encryption types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/cost-estimate
No summary
Estimate monthly S3 costs based on usage parameters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"storageCost": {
"type": "number"
},
"requestsCost": {
"type": "number"
},
"transferCost": {
"type": "number"
},
"totalMonthlyCost": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}
No summary
Get a specific S3 storage configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/storage/s3/{id}
No summary
Update an S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string",
"maxLength": 255
},
"endpoint_url": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"fallback_region": {
"type": [
"string",
"null"
]
},
"fallback_bucket": {
"type": [
"string",
"null"
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": [
"string",
"null"
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": [
"string",
"null"
]
},
"cdn_domain": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/storage/s3/{id}
No summary
Delete an S3 storage configuration
📤 RESPONSE 204
Default Response
POST
/api/v1/secure/storage/s3/{id}/test
No summary
Test S3 connection for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"latencyMs": {
"type": "number"
},
"latency_ms": {
"type": "integer"
},
"bucket_accessible": {
"type": "boolean"
},
"permissions": {
"type": "object",
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"list": {
"type": "boolean"
}
},
"additionalProperties": false
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
No summary
Rotate S3 credentials for a configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"access_key_id",
"secret_access_key"
],
"properties": {
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"rotation_type": {
"type": "string",
"enum": [
"scheduled",
"manual",
"emergency"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}/rotation-history
No summary
Get credential rotation history for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}/metrics
No summary
Get usage metrics for an S3 configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"metric_date": {
"type": "string"
},
"total_storage_bytes": {
"type": "integer"
},
"object_count": {
"type": "integer"
},
"get_requests": {
"type": "integer"
},
"put_requests": {
"type": "integer"
},
"delete_requests": {
"type": "integer"
},
"list_requests": {
"type": "integer"
},
"data_transfer_in_bytes": {
"type": "integer"
},
"data_transfer_out_bytes": {
"type": "integer"
},
"storage_cost_cents": {
"type": "integer"
},
"request_cost_cents": {
"type": "integer"
},
"transfer_cost_cents": {
"type": "integer"
},
"total_cost_cents": {
"type": "integer"
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
Search
GET
/api/v1/secure/search/
No summary
📤 RESPONSE 200
Default Response
Security
GET
/api/v1/secure/security/config
Get tenant security configuration
Returns CORS, CSRF, CSP, and HSTS configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/security/config
Update tenant security configuration
Updates CORS, CSRF, CSP, and HSTS settings
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"cors_origins": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_allowed_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_allowed_headers": {
"type": "array",
"items": {
"type": "string"
}
},
"cors_credentials": {
"type": "boolean"
},
"csrf_enabled": {
"type": "boolean"
},
"csp_policy": {
"type": "object",
"additionalProperties": true,
"description": "Content Security Policy directives"
},
"hsts_enabled": {
"type": "boolean"
},
"hsts_max_age": {
"type": "number"
},
"hsts_include_subdomains": {
"type": "boolean"
},
"hsts_preload": {
"type": "boolean"
},
"x_frame_options": {
"type": "string",
"enum": [
"DENY",
"SAMEORIGIN"
]
},
"x_content_type_options": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/security/csrf-token
Generate CSRF token
Generates a new CSRF token for the authenticated tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"token": {
"type": "string"
},
"expires_at": {
"type": "string"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/config
Get global security configuration
Returns platform-wide security settings (DOS, rate limiting, cache, circuit breaker). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/config
Update global security configuration
Update platform-wide security settings. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"dos_time_window_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"dos_block_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 86400
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number",
"minimum": 100,
"maximum": 50000
},
"queue_timeout_ms": {
"type": "number",
"minimum": 1000,
"maximum": 120000
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number",
"minimum": 3,
"maximum": 100
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number",
"minimum": 300,
"maximum": 604800
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number",
"minimum": 50,
"maximum": 99
},
"circuit_breaker_duration_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
},
"circuit_breaker_check_interval_seconds": {
"type": "number",
"minimum": 5,
"maximum": 60
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number",
"minimum": 100,
"maximum": 100000
},
"cache_default_ttl_seconds": {
"type": "number",
"minimum": 60,
"maximum": 3600
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"dos_enabled": {
"type": "boolean"
},
"dos_max_requests_per_ip": {
"type": "number"
},
"dos_time_window_seconds": {
"type": "number"
},
"dos_block_duration_seconds": {
"type": "number"
},
"queue_enabled": {
"type": "boolean"
},
"queue_max_size": {
"type": "number"
},
"queue_timeout_ms": {
"type": "number"
},
"ip_blacklist_enabled": {
"type": "boolean"
},
"ip_blacklist_auto_block": {
"type": "boolean"
},
"ip_blacklist_auto_block_threshold": {
"type": "number"
},
"ip_blacklist_auto_block_duration_seconds": {
"type": "number"
},
"circuit_breaker_enabled": {
"type": "boolean"
},
"circuit_breaker_cpu_threshold": {
"type": "number"
},
"circuit_breaker_duration_seconds": {
"type": "number"
},
"circuit_breaker_check_interval_seconds": {
"type": "number"
},
"cache_enabled": {
"type": "boolean"
},
"cache_max_entries": {
"type": "number"
},
"cache_default_ttl_seconds": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist
List IP blacklist entries
Returns all blocked IP addresses. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/security/ip-blacklist
Block an IP address
Add an IP address to the blacklist. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"ip_address"
],
"properties": {
"ip_address": {
"type": "string",
"description": "IPv4 or IPv6 address"
},
"reason": {
"type": "string",
"maxLength": 255,
"description": "Reason for blocking"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Expiration time (null = permanent)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/ip-blacklist/{id}
Get IP blacklist entry
Get details of a specific blocked IP. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/system/security/ip-blacklist/{id}
Update IP blacklist entry
Update reason or expiration of a blocked IP. System admin only.
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 255
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"ip_address": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"blocked_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"auto_blocked": {
"type": "boolean"
},
"failed_attempts": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/system/security/ip-blacklist/{id}
Unblock an IP address
Remove an IP address from the blacklist. System admin only.
📤 RESPONSE 204
No content
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/events
List security events
Returns security audit log entries. System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"ip_address": {
"type": "string",
"nullable": true
},
"user_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"tenant_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"details": {
"type": "object",
"additionalProperties": true
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high",
"critical"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/security/metrics
Get security metrics
Returns aggregated security metrics (blocked IPs, events, etc.). System admin only.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_blocked_ips": {
"type": "number"
},
"active_blocked_ips": {
"type": "number"
},
"permanent_blocks": {
"type": "number"
},
"temporary_blocks": {
"type": "number"
},
"auto_blocked_count": {
"type": "number"
},
"events_last_24h": {
"type": "number"
},
"events_by_type": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"events_by_severity": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Settings
GET
/api/v1/secure/settings/
No summary
📤 RESPONSE 200
Default Response
Space Members
GET
/api/v1/secure/spaces/{id}/members
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"space_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"space_id",
"user_id",
"role",
"created_at"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/members
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"userId": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
}
},
"required": [
"userId",
"role"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"space_id": {
"type": "string",
"format": "uuid"
},
"user_id": {
"type": "string",
"format": "uuid"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"space_id",
"user_id",
"role",
"created_at"
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/members/{userId}
No summary
📤 RESPONSE 204
Member successfully removed
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Spaces
GET
/api/v1/secure/spaces/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
],
"description": "Visibility/permission type: system (platform-managed, visible to all), custom (user-created, requires membership)"
},
"typeDefinition": {
"type": "string",
"description": "Schema type name or UUID for settings validation (defaults to wildcard if omitted)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Custom settings validated against type_definition schema"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"archived"
],
"description": "Space status (defaults to \"active\" if omitted)"
},
"homeLocation": {
"type": "object",
"nullable": true,
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
"tagIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Tag IDs to link to this space",
"nullable": true
},
"categoryIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Category IDs to link to this space",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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": {
"type": "string",
"maxLength": 1000
},
"type": {
"type": "string",
"enum": [
"system",
"custom"
],
"description": "Visibility/permission type: system (tenant-wide), default (standard), custom (user-defined)"
},
"typeDefinition": {
"type": "string",
"description": "Type definition name or UUID for settings validation (can be UUID or type_name)",
"nullable": true
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Custom settings validated against type_definition schema"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"archived"
],
"description": "Space status"
},
"homeLocation": {
"type": "object",
"nullable": true,
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"latitude",
"longitude"
],
"additionalProperties": false
},
"tagIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Tag IDs to link to this space",
"nullable": true
},
"categoryIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Category IDs to link to this space",
"nullable": true
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"enum": [
"system",
"default",
"custom"
]
},
"typeDefinitionId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"typeName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"archived",
"pending"
]
},
"manageable": {
"type": "boolean",
"description": "Whether current user can manage this space"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"translations_i18n": {
"type": "object",
"additionalProperties": true,
"description": "Translations for name/description (de, fr, it, etc.)"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Space-specific settings and metadata"
},
"categories": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"key",
"name"
],
"additionalProperties": false
}
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
},
"contacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"contact_type": {
"type": "string"
},
"value": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"contact_type",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"tenant_id",
"name",
"type",
"typeName",
"typeDefinitionId",
"status",
"created_at",
"updated_at",
"manageable",
"tags",
"categories",
"contacts"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}
No summary
📤 RESPONSE 204
Space successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/tags
No summary
Get all tags linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/tags
No summary
Link a tag to a space (creates tag if it doesn't exist)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name (will be normalized)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/tags/{tagId}
No summary
Unlink a tag from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/categories
No summary
Get all categories linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"parent_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"key": {
"type": "string"
},
"filter_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"level": {
"type": "number"
},
"name": {
"type": "string",
"description": "Localized name (preferred language with EN fallback)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Localized description"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO 639-1 language code"
},
"usage_count": {
"type": "number"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"key",
"level",
"name",
"usage_count",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/categories
No summary
Link a category to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"category_id"
],
"properties": {
"category_id": {
"type": "string",
"format": "uuid",
"description": "Category UUID"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"category_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/categories/{categoryId}
No summary
Unlink a category from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/spaces/{id}/contacts
No summary
Get contacts linked to a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/spaces/{id}/contacts
No summary
Link a contact to a space
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/spaces/{id}/contacts/{contactId}
No summary
Unlink a contact from a space
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Stats
GET
/api/v1/secure/stats/counts
Get entity counts
Get counts for multiple entity types in a single call. Optimized for dashboard views.
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"spaces": {
"type": "number",
"description": "Total number of spaces"
},
"resources": {
"type": "number",
"description": "Total number of resources"
},
"tags": {
"type": "number",
"description": "Total number of tags"
},
"categories": {
"type": "number",
"description": "Total number of categories"
},
"users": {
"type": "number",
"description": "Total number of users"
},
"groups": {
"type": "number",
"description": "Total number of groups"
}
},
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Storage
GET
/api/v1/secure/storage/system/status
No summary
Get tenant system storage status (quota, usage, available)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
},
"required": [
"tenant_id",
"enabled",
"quota_bytes",
"usage_bytes",
"available_bytes",
"usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/system/stats
No summary
Get system-wide storage statistics (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total_tenants": {
"type": "number"
},
"enabled_tenants": {
"type": "number"
},
"total_quota_bytes": {
"type": "number"
},
"total_usage_bytes": {
"type": "number"
},
"average_usage_percent": {
"type": "number"
}
},
"required": [
"total_tenants",
"enabled_tenants",
"total_quota_bytes",
"total_usage_bytes",
"average_usage_percent"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/s3/
No summary
List all S3 storage configurations for the current tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/storage/s3/
No summary
Create a new S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"region",
"bucket_name",
"access_key_id",
"secret_access_key"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"region": {
"type": "string",
"minLength": 1
},
"bucket_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"endpoint_url": {
"type": "string",
"maxLength": 500
},
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"fallback_region": {
"type": "string"
},
"fallback_bucket": {
"type": "string"
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": "string"
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": "string"
},
"cdn_domain": {
"type": "string"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/regions
No summary
Get available AWS S3 regions
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"location": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/encryption-types
No summary
Get available S3 encryption types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/cost-estimate
No summary
Estimate monthly S3 costs based on usage parameters
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"storageCost": {
"type": "number"
},
"requestsCost": {
"type": "number"
},
"transferCost": {
"type": "number"
},
"totalMonthlyCost": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}
No summary
Get a specific S3 storage configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/storage/s3/{id}
No summary
Update an S3 storage configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string",
"maxLength": 255
},
"endpoint_url": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"fallback_region": {
"type": [
"string",
"null"
]
},
"fallback_bucket": {
"type": [
"string",
"null"
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"type": [
"string",
"null"
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"type": [
"string",
"null"
]
},
"cdn_domain": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"endpoint_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"fallback_bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"versioning_enabled": {
"type": "boolean"
},
"encryption_type": {
"type": "string",
"enum": [
"NONE",
"SSE-S3",
"SSE-KMS",
"SSE-C"
]
},
"kms_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cors_rules": {
"type": "array"
},
"lifecycle_policies": {
"type": "array"
},
"cdn_enabled": {
"type": "boolean"
},
"cdn_distribution_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_monthly_cost_cents": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"error",
"disabled"
]
},
"last_connection_test": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_connection_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"connection_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"updated_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"name",
"region",
"bucket_name",
"versioning_enabled",
"encryption_type",
"cors_rules",
"lifecycle_policies",
"cdn_enabled",
"estimated_monthly_cost_cents",
"status",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/storage/s3/{id}
No summary
Delete an S3 storage configuration
📤 RESPONSE 204
Default Response
POST
/api/v1/secure/storage/s3/{id}/test
No summary
Test S3 connection for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"latencyMs": {
"type": "number"
},
"latency_ms": {
"type": "integer"
},
"bucket_accessible": {
"type": "boolean"
},
"permissions": {
"type": "object",
"properties": {
"read": {
"type": "boolean"
},
"write": {
"type": "boolean"
},
"delete": {
"type": "boolean"
},
"list": {
"type": "boolean"
}
},
"additionalProperties": false
},
"error": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
POST
/api/v1/secure/storage/s3/{id}/rotate-credentials
No summary
Rotate S3 credentials for a configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"access_key_id",
"secret_access_key"
],
"properties": {
"access_key_id": {
"type": "string",
"minLength": 1
},
"secret_access_key": {
"type": "string",
"minLength": 1
},
"rotation_type": {
"type": "string",
"enum": [
"scheduled",
"manual",
"emergency"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}/rotation-history
No summary
Get credential rotation history for a configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"rotation_type": {
"type": "string"
},
"old_key_expired_at": {
"type": [
"null",
"string"
]
},
"new_key_activated_at": {
"type": "string"
},
"rotated_by": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/s3/{id}/metrics
No summary
Get usage metrics for an S3 configuration
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"config_id": {
"type": "string"
},
"metric_date": {
"type": "string"
},
"total_storage_bytes": {
"type": "integer"
},
"object_count": {
"type": "integer"
},
"get_requests": {
"type": "integer"
},
"put_requests": {
"type": "integer"
},
"delete_requests": {
"type": "integer"
},
"list_requests": {
"type": "integer"
},
"data_transfer_in_bytes": {
"type": "integer"
},
"data_transfer_out_bytes": {
"type": "integer"
},
"storage_cost_cents": {
"type": "integer"
},
"request_cost_cents": {
"type": "integer"
},
"transfer_cost_cents": {
"type": "integer"
},
"total_cost_cents": {
"type": "integer"
},
"created_at": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
GET
/api/v1/secure/storage/buckets/
No summary
List storage buckets accessible to current user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/buckets/
No summary
Create new storage bucket
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"bucket_name",
"purpose"
],
"properties": {
"bucket_name": {
"type": "string",
"minLength": 3,
"maxLength": 63,
"pattern": "^[a-z0-9-]+$"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"max_file_size_bytes": {
"type": "number",
"minimum": 1024,
"maximum": 10737418240
},
"quota_bytes": {
"type": [
"number",
"null"
],
"minimum": 1024
},
"region": {
"type": "string",
"maxLength": 100
},
"cdn_domain": {
"type": "string",
"maxLength": 255
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000,
"default": 100
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
},
"public": {
"type": "boolean",
"default": false
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/providers
No summary
Get list of storage providers for selection dropdowns
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"enabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/providers/stats
No summary
Get storage provider statistics with health and usage data
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"supabase",
"tenant"
]
},
"enabled": {
"type": "boolean"
},
"health": {
"type": "string",
"enum": [
"online",
"degraded",
"offline"
]
},
"usage": {
"type": "object",
"properties": {
"used": {
"type": "number"
},
"total": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"percentage": {
"type": "number"
}
},
"required": [
"used",
"percentage"
],
"additionalProperties": false
},
"priority": {
"type": "number"
},
"isFallback": {
"type": "boolean"
},
"isSystem": {
"type": "boolean"
},
"fileCount": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"type",
"enabled",
"health",
"usage",
"priority",
"isFallback",
"isSystem",
"fileCount"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{id}
No summary
Get storage bucket details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"bucket_id": {
"type": "string"
},
"bucket_name": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"primary",
"archive",
"thumbnails",
"videos",
"documents"
]
},
"active": {
"type": "boolean"
},
"is_public": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number"
},
"quota_bytes": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"current_usage_bytes": {
"type": "number"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cdn_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"priority": {
"type": "number"
},
"tenant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"bucket_id",
"bucket_name",
"purpose",
"active",
"is_public",
"max_file_size_bytes",
"current_usage_bytes",
"priority",
"created_at",
"updated_at",
"allowed_mime_types"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/buckets/{id}
No summary
Update storage bucket
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"active": {
"type": "boolean"
},
"max_file_size_bytes": {
"type": "number",
"minimum": 1024
},
"quota_bytes": {
"type": [
"number",
"null"
],
"minimum": 1024
},
"region": {
"type": "string"
},
"cdn_domain": {
"type": "string"
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1000
},
"allowed_mime_types": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/buckets/{id}
No summary
Delete storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/policies
No summary
List RLS policies for storage.objects (read-only, informational)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaname": {
"type": "string"
},
"tablename": {
"type": "string"
},
"policyname": {
"type": "string"
},
"permissive": {
"type": "string"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"cmd": {
"type": "string"
},
"qual": {
"type": "string"
},
"with_check": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/files
No summary
List files in a storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "File or folder name"
},
"id": {
"type": [
"null",
"string"
],
"description": "File ID (null for folders)"
},
"path": {
"type": "string",
"description": "Full path to the file/folder"
},
"isFolder": {
"type": "boolean",
"description": "True if this is a folder"
},
"size": {
"type": "number",
"description": "File size in bytes (0 for folders)"
},
"mimeType": {
"type": [
"null",
"string"
],
"description": "MIME type of the file"
},
"isImage": {
"type": "boolean",
"description": "True if this is an image file"
},
"thumbnailUrl": {
"type": [
"null",
"string"
],
"description": "URL for thumbnail (images only)"
},
"publicUrl": {
"type": [
"null",
"string"
],
"description": "URL for public access/download"
},
"owner": {
"type": [
"null",
"string"
],
"description": "Owner user ID"
},
"createdBy": {
"type": [
"null",
"string"
],
"description": "Created by user ID"
},
"lastAccessedAt": {
"type": [
"null",
"string"
],
"description": "Last access timestamp"
},
"created_at": {
"type": "string",
"description": "Creation timestamp"
},
"updated_at": {
"type": "string",
"description": "Last update timestamp"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "File metadata from storage"
}
},
"required": [
"name",
"path",
"isFolder",
"size",
"isImage",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/buckets/{bucket_name}/files
No summary
Upload file to storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"id": {
"type": "string"
},
"fullPath": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/thumbnail/{*}
No summary
Get thumbnail for an image file
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/buckets/{bucket_name}/download/{*}
No summary
Download file from storage bucket
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/storage/buckets/{bucket_name}/files/{*}
No summary
Delete file from storage bucket
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/storage/test-upload
No summary
Test client upload to demonstrate RLS blocking (educational purpose)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"bucket_name": {
"type": "string"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/storage/distribution-config
No summary
Get bucket distribution configuration with configured bucket names
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"strategy": {
"type": "string"
},
"enableDistribution": {
"type": "boolean"
},
"buckets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"purpose": {
"type": "string"
},
"allowedMimeTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"priority": {
"type": "number"
},
"active": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"thumbnailBucket": {
"type": [
"null",
"string"
]
},
"imageBucket": {
"type": [
"null",
"string"
]
},
"videoBucket": {
"type": [
"null",
"string"
]
},
"documentBucket": {
"type": [
"null",
"string"
]
},
"fallbackChain": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/storage/distribution-config
No summary
Update bucket distribution configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"enum": [
"sequential",
"distributed"
]
},
"fallbackChain": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"thumbnailBucketId": {
"type": "string",
"format": "uuid"
},
"imageBucketId": {
"type": "string",
"format": "uuid"
},
"videoBucketId": {
"type": "string",
"format": "uuid"
},
"documentBucketId": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
System
GET
/api/v1/system/health
No summary
Multi-level health check (level=basic|ready|full)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"healthy"
],
"description": "Overall system health status"
},
"version": {
"type": "string",
"description": "API version (e.g., 1.1.123)"
},
"timestamp": {
"type": "string",
"description": "Health check timestamp (ISO 8601)"
},
"degradedServices": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of degraded service names (level=basic)"
},
"ready": {
"type": "boolean",
"description": "System ready status (level=ready, level=full)"
},
"environment": {
"type": "string",
"description": "Deployment environment (level=ready, level=full)"
},
"services": {
"type": "object",
"description": "Detailed health status of all services (level=full)",
"additionalProperties": true
},
"supabaseUrl": {
"type": "string",
"description": "Supabase instance URL used by this backend (origin)"
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/info
No summary
Complete system information with all service details
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded"
],
"description": "Overall system health status"
},
"version": {
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Full version string (e.g., 1.1.123)"
},
"major": {
"type": "number",
"description": "Major version number"
},
"minor": {
"type": "number",
"description": "Minor version number"
},
"build": {
"type": "number",
"description": "Build number (auto-incremented)"
},
"buildDate": {
"type": "string",
"description": "Build timestamp (ISO 8601)"
}
}
},
"timestamp": {
"type": "string",
"description": "System info check timestamp (ISO 8601)"
},
"environment": {
"type": "string",
"description": "Deployment environment (development, staging, production)"
},
"uptime": {
"type": "number",
"description": "Process uptime in seconds"
},
"services": {
"type": "object",
"description": "Detailed health status of all services",
"additionalProperties": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Service health status (healthy, degraded, unhealthy)"
},
"message": {
"type": "string",
"description": "Human-readable status message"
},
"responseTime": {
"type": "number",
"description": "Service response time in milliseconds"
},
"timestamp": {
"type": "string",
"description": "Last health check timestamp (ISO 8601)"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/dispatcher/run
No summary
Execute scheduled jobs (called by pg_cron)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
},
"jobs_skipped": {
"type": "number"
},
"health_status": {
"type": "object",
"properties": {
"overall": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"services": {
"type": "array",
"items": {
"type": "object",
"properties": {
"service_name": {
"type": "string"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
},
"alerts_sent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
GET
/api/v1/system/dispatcher/health
No summary
Get service health status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"overall": {
"type": "string",
"enum": [
"healthy",
"degraded"
]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"services": {
"type": "array",
"items": {
"type": "object",
"properties": {
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unhealthy"
]
},
"message": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
GET
/api/v1/system/dispatcher/status
No summary
Get dispatcher status and recent runs
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"serverless",
"pg-boss"
]
},
"last_run": {
"type": "object",
"nullable": true,
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
},
"health_status": {
"type": "object"
}
}
},
"recent_runs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"duration_ms": {
"type": "number"
},
"jobs_executed": {
"type": "number"
},
"jobs_failed": {
"type": "number"
}
}
}
},
"recent_alerts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"severity": {
"type": "string"
},
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"acknowledged": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
POST
/api/v1/system/dispatcher/alerts/{id}/acknowledge
No summary
Acknowledge a system alert
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 503
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"email": {
"type": "string"
},
"isSystemAdmin": {
"type": "boolean"
},
"isTenantAdmin": {
"type": "boolean"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"effectivePermissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"userId",
"tenantId",
"isSystemAdmin",
"isTenantAdmin",
"groups",
"effectivePermissions"
]
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/permissions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/spaces
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"space_id": {
"type": "string"
},
"space_name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"manager",
"reader"
]
}
},
"required": [
"space_id",
"space_name",
"role"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/spaces/manageable
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/me/resources/manageable
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"space_id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"space_id",
"name"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/iam/can
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"allowed": {
"type": "boolean"
}
},
"required": [
"allowed"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/features/catalog
No summary
Get catalog of all available features (system admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"core",
"premium",
"experimental"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "string"
}
},
"defaultEnabled": {
"type": "boolean"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tags
GET
/api/v1/secure/taxonomy/tags/
No summary
List tags with optional search
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Localized display name (preferred language with EN fallback)"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total": {
"type": "number"
}
},
"required": [
"data",
"total"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/{id}
No summary
Get tag by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/tags/{id}
No summary
Delete tag (admin only)
📤 RESPONSE 204
Tag deleted successfully
POST
/api/v1/secure/taxonomy/tags/link
No summary
Link tag to entity (implicit tag creation)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name",
"entity_type",
"entity_id"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/link/bulk
No summary
Link multiple tags to entity at once
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_names",
"entity_type",
"entity_id"
],
"properties": {
"tag_names": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"minItems": 1,
"maxItems": 50
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
DELETE
/api/v1/secure/taxonomy/tags/{id}/unlink
No summary
Unlink tag from entity (auto-delete tag if no links remain)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"entity_type",
"entity_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
}
}
}
📤 RESPONSE 204
Tag unlinked successfully
GET
/api/v1/secure/taxonomy/tags/entity
No summary
Get all tags for an entity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
]
}
GET
/api/v1/secure/taxonomy/tags/cloud
No summary
Get tag cloud (most used tags)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tag_id": {
"type": "string",
"format": "uuid"
},
"tag_name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name"
},
"count": {
"type": "number",
"description": "Usage count"
}
},
"required": [
"tag_id",
"tag_name",
"display_name",
"count"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
GET
/api/v1/secure/taxonomy/tags/{id}/entities
No summary
Get all entities tagged with this tag (reverse lookup filter)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"tag_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"space",
"resource",
"tenant",
"group"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"tag_id",
"entity_type",
"entity_id",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/curated
Create curated tag
Create a persistent curated tag (tenant admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"tag_name"
],
"properties": {
"tag_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Tag name"
},
"group_id": {
"type": "string",
"format": "uuid",
"description": "Group ID for group-owned tags (optional)"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
PATCH
/api/v1/secure/taxonomy/tags/{id}/upgrade
Upgrade tag to persistent
Upgrade a tag to persistent/curated status (tenant admin only)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
POST
/api/v1/secure/taxonomy/tags/cleanup
Cleanup unused tags
Delete non-persistent tags with no entity links (tenant admin only)
📤 RESPONSE 200
Inline Schema
Response: Cleanup completed
Schema: Cleanup completed
{
"description": "Cleanup completed",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deleted_count": {
"type": "number",
"description": "Number of tags deleted"
}
}
}
}
}
POST
/api/v1/secure/taxonomy/tags/bulk-update
Bulk update tags
Update multiple tags in one transaction (all or nothing)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"updates"
],
"properties": {
"updates": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Tag ID"
},
"persistent": {
"type": "boolean",
"description": "Set persistent/curated status"
}
}
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Normalized name (lowercase)"
},
"display_name": {
"type": "string",
"description": "Display name in base language"
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (e.g., en, de, fr, it)"
},
"translations_i18n": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
},
"description": "Translations for all tenant languages (de, fr, it, etc.)"
},
"usage_count": {
"type": "number",
"description": "Number of entities linked to this tag"
},
"persistent": {
"type": "boolean",
"description": "If true, tag exists without entity links (curated tag)"
},
"owner_id": {
"type": "string",
"format": "uuid",
"description": "Owner UUID (user or group)"
},
"owner_type": {
"type": "string",
"enum": [
"user",
"group"
],
"description": "Owner type"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"name",
"display_name",
"language",
"translations_i18n",
"usage_count",
"persistent",
"owner_id",
"owner_type",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
Tenant Metrics
GET
/api/v1/secure/tenants/{id}/metrics/snapshot
Get metrics snapshot
Retrieve real-time snapshot of current tenant metrics
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"tenantName": {
"type": "string",
"description": "Tenant name"
},
"users": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of users"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active users (last 30 days)"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of spaces"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active spaces"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of resources"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active resources"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"usedBytes": {
"type": "integer",
"minimum": 0,
"description": "Storage used in bytes"
},
"usedGB": {
"type": "number",
"minimum": 0,
"description": "Storage used in gigabytes"
}
},
"required": [
"usedBytes",
"usedGB"
],
"additionalProperties": false
},
"snapshotAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of snapshot"
}
},
"required": [
"tenantId",
"tenantName",
"users",
"spaces",
"resources",
"storage",
"snapshotAt"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/daily
Get daily metrics
Retrieve historical daily metrics for a tenant (max 90 days)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Metrics record UUID"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"metricDate": {
"type": "string",
"format": "date",
"description": "Metrics date (ISO 8601)"
},
"users": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of users"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active users (last 30 days)"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of spaces"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active spaces"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of resources"
},
"active": {
"type": "integer",
"minimum": 0,
"description": "Active resources"
}
},
"required": [
"total",
"active"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"usedBytes": {
"type": "integer",
"minimum": 0,
"description": "Storage used in bytes"
},
"usedGB": {
"type": "number",
"minimum": 0,
"description": "Storage used in gigabytes"
}
},
"required": [
"usedBytes",
"usedGB"
],
"additionalProperties": false
},
"apiCalls": {
"type": [
"null",
"integer"
],
"minimum": 0,
"description": "API calls count (if tracked)"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp"
}
},
"required": [
"id",
"tenantId",
"metricDate",
"users",
"spaces",
"resources",
"storage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "Array of daily metrics (sorted by date desc)"
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/monthly
Get monthly metrics
Retrieve historical monthly metrics for a tenant (max 12 months)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Metrics record UUID"
},
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"year": {
"type": "integer",
"minimum": 2024,
"description": "Year"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"description": "Month (1-12)"
},
"users": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total users"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak users in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"spaces": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total spaces"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak spaces in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"resources": {
"type": "object",
"properties": {
"average": {
"type": "integer",
"minimum": 0,
"description": "Average total resources"
},
"peak": {
"type": "integer",
"minimum": 0,
"description": "Peak resources in any day"
}
},
"required": [
"average",
"peak"
],
"additionalProperties": false
},
"storage": {
"type": "object",
"properties": {
"averageBytes": {
"type": "integer",
"minimum": 0,
"description": "Average storage in bytes"
},
"averageGB": {
"type": "number",
"minimum": 0,
"description": "Average storage in GB"
},
"peakBytes": {
"type": "integer",
"minimum": 0,
"description": "Peak storage in bytes"
},
"peakGB": {
"type": "number",
"minimum": 0,
"description": "Peak storage in GB"
}
},
"required": [
"averageBytes",
"averageGB",
"peakBytes",
"peakGB"
],
"additionalProperties": false
},
"totalApiCalls": {
"type": [
"null",
"integer"
],
"minimum": 0,
"description": "Total API calls for the month"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Record creation timestamp"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Record update timestamp"
}
},
"required": [
"id",
"tenantId",
"year",
"month",
"users",
"spaces",
"resources",
"storage",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "Array of monthly metrics (sorted by year/month desc)"
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/metrics/quota-warnings
Get quota warnings
Check quota warnings for a tenant (compares usage against limits)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenantId": {
"type": "string",
"format": "uuid",
"description": "Tenant UUID"
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"resource": {
"type": "string",
"enum": [
"users",
"spaces",
"resources",
"storage"
],
"description": "Resource type"
},
"current": {
"type": "number",
"minimum": 0,
"description": "Current usage"
},
"limit": {
"type": "number",
"minimum": 0,
"description": "Configured limit"
},
"percentage": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Usage percentage"
},
"threshold": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Warning threshold"
},
"exceeded": {
"type": "boolean",
"description": "Whether limit is exceeded"
}
},
"required": [
"resource",
"current",
"limit",
"percentage",
"threshold",
"exceeded"
],
"additionalProperties": false
},
"description": "Array of quota warnings (only resources at/above threshold)"
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of check"
}
},
"required": [
"tenantId",
"warnings",
"checkedAt"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenant Rate Limits
GET
/api/v1/secure/tenants/{id}/rate-limits
List rate limit configurations
Get all rate limit configurations for a tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/rate-limits
Create rate limit configuration
Create a new rate limit configuration for a tenant
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number",
"minimum": 1
},
"window_seconds": {
"type": "number",
"minimum": 1
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean",
"default": true
}
},
"required": [
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type"
],
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Get rate limit configuration
Get a single rate limit configuration by ID
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Update rate limit configuration
Update an existing rate limit configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number",
"minimum": 1
},
"window_seconds": {
"type": "number",
"minimum": 1
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"endpoint_pattern": {
"type": "string"
},
"max_requests": {
"type": "number"
},
"window_seconds": {
"type": "number"
},
"scope_type": {
"type": "string",
"enum": [
"per_ip",
"per_user",
"per_device",
"per_app_account",
"per_tenant"
]
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"endpoint_pattern",
"max_requests",
"window_seconds",
"scope_type",
"enabled",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}/rate-limits/{limitId}
Delete rate limit configuration
Delete a rate limit configuration
📤 RESPONSE 204
Inline Schema
Response: Default Response
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenant Settings
GET
/api/v1/secure/tenants/{id}/settings
Get all tenant settings
Retrieve all settings categories for a tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"general": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "IANA timezone (e.g., Europe/Zurich)",
"pattern": "^[A-Za-z_]+/[A-Za-z_]+$"
},
"locale": {
"type": "string",
"description": "Locale code (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
"limits": {
"type": "object",
"properties": {
"max_users": {
"type": "number",
"description": "Maximum users (-1 = unlimited)"
},
"max_spaces": {
"type": "number",
"description": "Maximum spaces (-1 = unlimited)"
},
"max_resources": {
"type": "number",
"description": "Maximum resources (-1 = unlimited)"
},
"max_storage_gb": {
"type": "number",
"description": "Maximum storage in GB"
},
"max_api_calls_per_day": {
"type": "number",
"description": "Maximum API calls per day"
}
},
"required": [
"max_users",
"max_spaces",
"max_resources",
"max_storage_gb",
"max_api_calls_per_day"
],
"additionalProperties": false
},
"integrations": {
"type": "object",
"properties": {
"calendar": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Calendar integration (Google, Outlook, iCal)"
},
"billing": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "Integration provider name"
},
"api_key_vault_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Reference to encrypted API key in Supabase Vault"
},
"enabled": {
"type": "boolean",
"description": "Whether integration is active"
},
"config": {
"type": "object",
"additionalProperties": true,
"description": "Provider-specific configuration"
}
},
"required": [
"provider",
"enabled"
],
"additionalProperties": false,
"description": "Billing integration (Stripe, PayPal)"
}
},
"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"
},
"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
}
},
"required": [
"general",
"limits",
"integrations",
"notifications"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/settings/{category}
Get category settings
Retrieve settings for a specific category
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications"
]
},
"settings": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"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"
},
{
"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
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/settings/{category}
Update category settings
Update settings for a specific category (partial merge)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"settings": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"additionalProperties": true,
"description": "Extensible integration configurations"
},
{
"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
}
],
"description": "Partial settings update (merges with existing)"
}
},
"required": [
"settings"
],
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications"
]
},
"settings": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"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"
},
{
"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
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/settings/{category}/reset
Reset settings to defaults
Reset category settings to default values based on tenant type
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"tenant_type": {
"type": "string",
"enum": [
"trial",
"paid",
"enterprise"
],
"description": "Tenant type for default template (default: trial)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications"
]
},
"settings": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"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"
},
{
"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
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"category",
"settings"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/settings/history
Get settings history
Retrieve audit trail of settings changes
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"category": {
"type": "string",
"enum": [
"general",
"limits",
"integrations",
"notifications"
]
},
"settings_before": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"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"
},
{
"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
},
{
"type": "null"
}
],
"description": "Settings before change (null on first create)"
},
"settings_after": {
"anyOf": [
{
"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 (e.g., en-GB, en-US, de-DE)",
"pattern": "^[a-z]{2}-[A-Z]{2}$"
},
"date_format": {
"type": "string",
"enum": [
"YYYY-MM-DD",
"DD.MM.YYYY",
"MM/DD/YYYY"
]
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
]
}
},
"required": [
"timezone",
"locale",
"date_format",
"time_format"
],
"additionalProperties": false
},
{
"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
},
{
"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)"
}
},
"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"
},
{
"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
}
]
},
"changed_by": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "User who made the change"
},
"changed_at": {
"type": "string",
"format": "date-time"
},
"change_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ip_address": {
"anyOf": [
{
"type": "string",
"format": "ipv4"
},
{
"type": "string",
"format": "ipv6"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"tenant_id",
"category",
"settings_after",
"changed_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Tenants
GET
/api/v1/secure/tenants/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"domain",
"ownerEmail",
"ownerPassword"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"domain": {
"type": "string",
"minLength": 2,
"maxLength": 255,
"pattern": "^[a-z0-9.-]+$"
},
"ownerEmail": {
"type": "string",
"format": "email"
},
"ownerPassword": {
"type": "string",
"minLength": 8,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 1000
},
"type": {
"type": "string",
"enum": [
"trial",
"paid",
"enterprise"
]
},
"contactEmail": {
"type": "string",
"format": "email"
},
"contactPhone": {
"type": "string",
"maxLength": 50
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"defaultLanguage": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "Default language (ISO 639-1, e.g., en, de, fr)"
},
"additionalLanguages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"description": "Additional supported languages"
},
"settings": {
"type": "object"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"domain": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 63
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"additional_languages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"storage_distribution_strategy": {
"type": "string",
"enum": [
"sequential",
"distributed"
],
"description": "File distribution strategy: sequential (fill in order) or distributed (group by space/resource)"
},
"storage_fallback_chain": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Array of storage provider IDs in fallback order"
},
"settings": {
"type": "object"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}
No summary
📤 RESPONSE 204
Tenant successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/info
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant": {
"type": "object",
"additionalProperties": true
},
"admin": {
"type": "object",
"additionalProperties": true
},
"api": {
"type": "object",
"additionalProperties": true
},
"groups": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"spaces": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/language-sync-status
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Error details"
}
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
]
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Error details"
}
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
]
}
}
]
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/language-sync/history
Get language sync history
Get paginated language sync job history with server-side filtering
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"operation": {
"type": "string",
"enum": [
"add",
"remove"
]
},
"language_code": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"completed",
"failed"
]
},
"entities_processed": {
"type": "integer"
},
"entities_total": {
"type": "integer"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"started_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"operation",
"language_code",
"status",
"entities_processed",
"entities_total",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
],
"additionalProperties": false
}
},
"required": [
"data",
"pagination"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/env
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/json
No summary
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/activate
No summary
Activate tenant (pending → trial, or inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for activation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/upgrade
No summary
Upgrade tenant type (trial → paid → enterprise)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"target_type"
],
"properties": {
"target_type": {
"type": "string",
"enum": [
"paid",
"enterprise"
],
"description": "Target plan type"
},
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for upgrade (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/suspend
No summary
Suspend tenant (active → inactive)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for suspension (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/reactivate
No summary
Reactivate tenant (inactive → active)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for reactivation (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/tenants/{id}/lifecycle/{id}/archive
No summary
Archive tenant (inactive → retired)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500,
"description": "Reason for archiving (audit trail)"
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/lifecycle/{id}/history
No summary
Get lifecycle history (audit trail) for tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"from_status": {
"type": "string"
},
"to_status": {
"type": "string"
},
"from_type": {
"type": "string"
},
"to_type": {
"type": "string"
},
"action": {
"type": "string"
},
"reason": {
"type": "string",
"nullable": true
},
"performed_by": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"tenant_id",
"from_status",
"to_status",
"action",
"performed_by",
"created_at"
]
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/storage-config
No summary
Get tenant storage provider configuration (credentials masked)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"credentials_encrypted": {
"type": "boolean"
},
"config": {
"type": "object",
"additionalProperties": true
},
"fallback_enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/storage-config
No summary
Update tenant storage provider configuration
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"supabase",
"s3",
"azure"
]
},
"credentials_encrypted": {
"type": "object",
"additionalProperties": true
},
"config": {
"type": "object",
"additionalProperties": true
},
"fallback_enabled": {
"type": "boolean"
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/tenants/{id}/storage-config
No summary
Delete tenant storage configuration (revert to default Supabase)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/dashboard
Get tenant dashboard
Get all tenant dashboard data in one call: tenant info, metrics, storage, recent activity, and language sync status
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"description": "Tenant name"
},
"slug": {
"type": "string",
"description": "URL-friendly identifier"
},
"domain": {
"type": "string",
"description": "Tenant domain"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tenant description"
},
"type": {
"type": "string",
"enum": [
"system",
"trial",
"paid",
"enterprise"
],
"description": "Subscription type"
},
"contact_email": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Primary contact email"
},
"contact_phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Primary contact phone"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "Tenant-specific settings and configuration"
},
"default_language": {
"type": "string",
"description": "Default language (ISO 639-1, immutable after creation)"
},
"additional_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional supported languages (ISO 639-1 codes)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"name",
"slug",
"domain",
"status",
"type",
"settings",
"default_language",
"additional_languages",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"metrics": {
"type": "object",
"properties": {
"users": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"active": {
"type": "number"
},
"trend": {
"type": "number",
"description": "Percentage change vs last period"
}
},
"required": [
"total",
"active"
]
},
"spaces": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"active": {
"type": "number"
},
"trend": {
"type": "number"
}
},
"required": [
"total",
"active"
]
},
"resources": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"trend": {
"type": "number"
}
},
"required": [
"total"
]
},
"apiRequests": {
"type": "object",
"properties": {
"last30d": {
"type": "number"
}
},
"required": [
"last30d"
]
}
},
"required": [
"users",
"spaces",
"resources",
"apiRequests"
]
},
"storage": {
"type": "object",
"properties": {
"used": {
"type": "number",
"description": "Storage used in bytes"
},
"limit": {
"type": "number",
"description": "Storage limit in bytes"
},
"percent": {
"type": "number",
"description": "Usage percentage"
}
},
"required": [
"used",
"limit",
"percent"
]
},
"recentActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
}
}
},
"required": [
"type",
"entity_id",
"entity_type",
"timestamp"
]
},
"description": "Last 10 activities"
},
"languageSync": {
"type": "object",
"properties": {
"activeJobs": {
"type": "number"
},
"lastSync": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"required": [
"activeJobs"
]
}
},
"required": [
"tenant",
"metrics",
"storage",
"recentActivity",
"languageSync"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/tenants/{id}/log-retention
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"retention_days": {
"type": "number",
"enum": [
30,
60,
90
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/log-retention
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"retention_days"
],
"properties": {
"retention_days": {
"type": "number",
"enum": [
30,
60,
90
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"retention_days": {
"type": "number"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/tenants/{id}/system-storage
No summary
Update tenant system storage configuration (system admin only)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number",
"minimum": 1
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tenant_id": {
"type": "string",
"format": "uuid"
},
"enabled": {
"type": "boolean"
},
"quota_bytes": {
"type": "number"
},
"usage_bytes": {
"type": "number"
},
"available_bytes": {
"type": "number"
},
"usage_percent": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Type Definitions
GET
/api/v1/secure/type-definitions/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/type-definitions/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"label",
"schemaDefinition"
],
"properties": {
"name": {
"type": "string",
"description": "Unique type name (kebab-case recommended)",
"pattern": "^[a-z0-9-]+$",
"minLength": 2,
"maxLength": 100
},
"label": {
"type": "string",
"description": "Human-readable label",
"minLength": 2,
"maxLength": 255
},
"description": {
"type": "string",
"description": "Optional description of the type",
"maxLength": 1000
},
"category": {
"type": "string",
"description": "Category classification (e.g., vehicle, person, location)",
"maxLength": 100
},
"schemaDefinition": {
"type": "object",
"description": "JSON Schema for validating settings",
"required": [
"properties"
],
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/type-definitions/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/type-definitions/{id}
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 2,
"maxLength": 255
},
"description": {
"type": "string",
"maxLength": 1000
},
"is_active": {
"type": "boolean"
},
"schemaDefinition": {
"type": "object",
"properties": {
"properties": {
"type": "object",
"additionalProperties": true
},
"required": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"data"
]
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/type-definitions/{id}
No summary
📤 RESPONSE 204
Inline Schema
Response: Default Response
{
"type": "object",
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
User Groups
GET
/api/v1/secure/groups/users/{userId}/permissions
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Users
GET
/api/v1/secure/users/
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"total",
"limit",
"offset",
"hasMore"
]
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/
No summary
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"email",
"password"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string",
"minLength": 8
},
"displayName": {
"type": "string"
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}
No summary
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
PATCH
/api/v1/secure/users/{id}
Update user profile
Update user profile information (first name, last name, display name, locale)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"firstName": {
"type": [
"string",
"null"
]
},
"middleName": {
"type": [
"string",
"null"
]
},
"lastName": {
"type": [
"string",
"null"
]
},
"displayName": {
"type": [
"string",
"null"
]
},
"locale": {
"type": "string",
"enum": [
"en",
"de",
"fr",
"es",
"it"
]
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/context
Get user context
Get user with all related data: groups, permissions, and recent activity
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"active",
"inactive",
"maintenance",
"retired",
"pending"
]
},
"first_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local first name (e.g., Thai: สมชาย)"
},
"middle_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local middle name (optional)"
},
"last_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native/local last name (e.g., Thai: ใจดี)"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Nickname/alias for public display"
},
"avatar_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"profileImage": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"media_file_id": {
"type": "string",
"format": "uuid"
},
"is_main": {
"type": "boolean"
},
"sort_order": {
"type": "number"
},
"public_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to media file"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Thumbnail URL (small variant) for display"
},
"caption": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"media_file_id",
"is_main",
"sort_order",
"public_url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Profile image from media service (main image for user)"
},
"locale": {
"type": "string",
"description": "User preferred locale (ISO 639-1)"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tenant_id",
"email",
"status",
"locale",
"created_at",
"updated_at"
],
"additionalProperties": false
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"permissions"
]
}
},
"permissions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"resource": {
"type": "string"
},
"action": {
"type": "string"
}
},
"required": [
"resource",
"action"
]
},
"description": "Flattened list of all user permissions"
},
"recentActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string"
},
"timestamp": {
"type": "string",
"format": "date-time"
}
},
"required": [
"type",
"entity_id",
"entity_type",
"timestamp"
]
},
"description": "Last 5 activities"
}
},
"required": [
"user",
"groups",
"permissions",
"recentActivity"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/users/{id}/contacts
No summary
Get contacts linked to a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/users/{id}/contacts
No summary
Link a contact to a user
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"contactId"
],
"properties": {
"contactId": {
"type": "string",
"format": "uuid"
},
"isPrimary": {
"type": "boolean"
}
},
"additionalProperties": false
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"entity_type": {
"type": "string",
"enum": [
"user",
"space",
"resource"
]
},
"entity_id": {
"type": "string",
"format": "uuid"
},
"contact_id": {
"type": "string",
"format": "uuid"
},
"is_primary": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"first_name": {
"type": [
"null",
"string"
],
"description": "Passport first name (romanized)"
},
"middle_name": {
"type": [
"null",
"string"
],
"description": "Passport middle name (optional)"
},
"last_name": {
"type": [
"null",
"string"
],
"description": "Passport last name (romanized)"
},
"email": {
"type": [
"null",
"string"
],
"format": "email"
},
"phone": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
],
"format": "uri"
},
"address": {
"anyOf": [
{
"type": "object",
"properties": {
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"street_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postal_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"country_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"notes": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": [
"null",
"string"
],
"format": "uuid"
},
"updated_by": {
"type": [
"null",
"string"
],
"format": "uuid"
}
},
"required": [
"id",
"tenant_id",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"required": [
"id",
"tenant_id",
"entity_type",
"entity_id",
"contact_id",
"is_primary",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"data"
],
"additionalProperties": false
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 409
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
DELETE
/api/v1/secure/users/{id}/contacts/{contactId}
No summary
Unlink a contact from a user
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
},
"required": [
"success"
],
"additionalProperties": false
}
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
Webhooks
POST
/api/v1/services/webhooks/sendgrid
No summary
Handle SendGrid webhook events (delivered, bounced, opened, clicked)
📥 REQUEST BODY
Inline Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"event": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"timestamp": {
"type": "number"
},
"sg_message_id": {
"type": "string"
},
"reason": {
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"event",
"email",
"timestamp"
]
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"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/services/webhooks/twilio
No summary
Handle Twilio status callbacks (SMS, WhatsApp delivery status)
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"MessageSid": {
"type": "string"
},
"MessageStatus": {
"type": "string"
},
"ErrorCode": {
"type": "string"
},
"ErrorMessage": {
"type": "string"
}
},
"required": [
"MessageSid",
"MessageStatus"
]
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"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/webhooks/subscriptions
No summary
List all webhook subscriptions for the tenant
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"limit": {
"type": "number"
},
"offset": {
"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
POST
/api/v1/secure/webhooks/subscriptions
No summary
Create a new webhook subscription
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"required": [
"name",
"url",
"events"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500,
"nullable": true
},
"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": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Custom headers to include in webhook requests"
}
}
}
📤 RESPONSE 201
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"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/webhooks/event-types
No summary
List available webhook event types
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
GET
/api/v1/secure/webhooks/subscriptions/{id}
No summary
Get a specific webhook subscription
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"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/webhooks/subscriptions/{id}
No summary
Update a webhook subscription
📥 REQUEST BODY
Inline Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500,
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"enabled": {
"type": "boolean"
},
"secret": {
"type": "string"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
}
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"nullable": true
},
"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
DELETE
/api/v1/secure/webhooks/subscriptions/{id}
No summary
Delete a webhook subscription
📤 RESPONSE 204
Successfully deleted
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 403
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 404
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 422
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 500
- Default Response
→ See StandardErrorResponse
POST
/api/v1/secure/webhooks/subscriptions/{id}/test
No summary
Send a test webhook to verify the subscription endpoint
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"statusCode": {
"type": "number",
"nullable": true
},
"responseBody": {
"type": "string",
"nullable": true
},
"error": {
"type": "string",
"nullable": true
},
"attempts": {
"type": "number"
},
"deliveryTime": {
"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/webhooks/subscriptions/{id}/logs
No summary
Get delivery logs for a webhook subscription
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"subscription_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"event": {
"type": "string"
},
"url": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"success",
"failed"
]
},
"status_code": {
"type": "number",
"nullable": true
},
"response_body": {
"type": "string",
"nullable": true
},
"error": {
"type": "string",
"nullable": true
},
"attempts": {
"type": "number"
},
"delivery_time_ms": {
"type": "number"
},
"created_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/webhooks/subscriptions/{id}/stats
No summary
Get delivery statistics for a webhook subscription (last 30 days)
📤 RESPONSE 200
Inline Schema
Response: Default Response
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"success": {
"type": "number"
},
"failed": {
"type": "number"
},
"successRate": {
"type": "number"
},
"avgDeliveryTime": {
"type": "number"
}
}
}
}
}
📤 RESPONSE 400
- Default Response
→ See StandardErrorResponse
📤 RESPONSE 401
- Default Response
→ See StandardErrorResponse
📤 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
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
}