{ "openapi": "3.0.3", "info": { "title": "MamuteCloud API", "description": "Unified MamuteCloud API: CDN, DNS, SSL, Object Storage, IAM, Organization, Analytics. Management API base https://api.mamutecloud.com. S3 data plane base https://s3-us-east-1.mamutecloud.com (path-style, region us-east-1).", "version": "1.0.0", "contact": { "name": "MamuteCloud", "url": "https://docs.mamutecloud.com" } }, "servers": [ { "url": "https://api.mamutecloud.com", "description": "Production server" } ], "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Raw project API key (starts with mamute-) in the Authorization header." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" }, "data": { "type": "object", "description": "Response data (varies by endpoint)" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Operation failed" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation errors" } } }, "CustomHeader": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "CustomErrorResponse": { "type": "object", "required": [ "error_code", "response_page_path" ], "properties": { "error_code": { "type": "integer", "enum": [ 400, 403, 404, 405, 414, 416, 500, 501, 502, 503, 504 ] }, "response_page_path": { "type": "string", "description": "Must start with '/'" }, "response_code": { "type": "string" }, "error_caching_min_ttl": { "type": "integer" } } }, "CreateOriginGroupRequest": { "type": "object", "required": [ "resource_id" ], "properties": { "resource_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "hostname": { "type": "string", "description": "Required unless type is storage" }, "origin_path": { "type": "string" }, "protocol_policy": { "type": "string", "enum": [ "http-only", "https-only", "match-viewer" ] }, "http_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "https_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "origin_ssl_protocols": { "type": "array", "items": { "type": "string", "enum": [ "TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3" ] } }, "custom_headers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomHeader" } }, "type": { "type": "string", "enum": [ "s3", "custom", "storage" ] }, "connection_attempts": { "type": "integer", "minimum": 1, "maximum": 3 }, "connection_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 10 }, "response_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "keepalive_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "bucket_id": { "type": "string", "format": "uuid", "description": "Required when type is storage" } } }, "UpdateOriginGroupRequest": { "type": "object", "properties": { "name": { "type": "string" }, "hostname": { "type": "string" }, "origin_path": { "type": "string" }, "protocol_policy": { "type": "string", "enum": [ "http-only", "https-only", "match-viewer" ] }, "http_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "https_port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "origin_ssl_protocols": { "type": "array", "items": { "type": "string", "enum": [ "TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3" ] } }, "custom_headers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomHeader" } }, "type": { "type": "string", "enum": [ "s3", "custom", "storage" ] }, "connection_attempts": { "type": "integer", "minimum": 1, "maximum": 3 }, "connection_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 10 }, "response_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "keepalive_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "bucket_id": { "type": "string", "format": "uuid" } } }, "OriginGroupResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "hostname": { "type": "string" }, "origin_path": { "type": "string" }, "protocol_policy": { "type": "string", "enum": [ "http-only", "https-only", "match-viewer" ] }, "http_port": { "type": "integer" }, "https_port": { "type": "integer" }, "origin_ssl_protocols": { "type": "array", "items": { "type": "string" } }, "custom_headers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomHeader" } }, "type": { "type": "string", "enum": [ "s3", "custom", "storage" ] }, "connection_attempts": { "type": "integer" }, "connection_timeout_seconds": { "type": "integer" }, "response_timeout_seconds": { "type": "integer" }, "keepalive_timeout_seconds": { "type": "integer" }, "bucket_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InlineOriginGroupRequest": { "type": "object", "properties": { "name": { "type": "string" }, "hostname": { "type": "string" }, "origin_path": { "type": "string" }, "protocol_policy": { "type": "string", "enum": [ "http-only", "https-only", "match-viewer" ] }, "http_port": { "type": "integer" }, "https_port": { "type": "integer" }, "origin_ssl_protocols": { "type": "array", "items": { "type": "string", "enum": [ "TLSv1", "TLSv1.1", "TLSv1.2", "TLSv1.3" ] } }, "custom_headers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomHeader" } }, "type": { "type": "string", "enum": [ "s3", "custom", "storage" ] }, "connection_attempts": { "type": "integer" }, "connection_timeout_seconds": { "type": "integer" }, "response_timeout_seconds": { "type": "integer" }, "keepalive_timeout_seconds": { "type": "integer" }, "bucket_id": { "type": "string", "format": "uuid" } } }, "CreateResourceRequest": { "type": "object", "required": [ "name", "origin_group" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "origin_group": { "$ref": "#/components/schemas/InlineOriginGroupRequest" }, "custom_error_responses": { "type": "array", "items": { "$ref": "#/components/schemas/CustomErrorResponse" } }, "subdomain_routing": { "type": "boolean", "description": "S3/storage origins only. Serve each hostname from its own bucket folder instead of the bucket root. Same flag as the one on the default behavior, applied at creation. Default false.", "default": false } } }, "UpdateResourceOriginGroupItem": { "type": "object", "required": [ "id", "priority" ], "properties": { "id": { "type": "string", "format": "uuid" }, "priority": { "type": "integer" }, "action": { "type": "string", "enum": [ "add", "remove", "update" ] } } }, "UpdateResourceBehaviorItem": { "type": "object", "required": [ "priority" ], "properties": { "id": { "type": "string", "format": "uuid" }, "priority": { "type": "integer" }, "action": { "type": "string", "enum": [ "add", "remove", "update" ] }, "name": { "type": "string" }, "path_pattern": { "type": "string" }, "viewer_protocol_policy": { "type": "string", "enum": [ "allow-all", "https-only", "redirect-to-https" ] }, "allowed_methods": { "type": "array", "items": { "type": "string" } }, "cached_methods": { "type": "array", "items": { "type": "string" } }, "compress_objects": { "type": "boolean" }, "cache_min_ttl": { "type": "integer" }, "cache_default_ttl": { "type": "integer" }, "cache_max_ttl": { "type": "integer" }, "cache_based_on_query_string": { "type": "boolean" }, "cache_query_string_whitelist": { "type": "array", "items": { "type": "string" } }, "cache_based_on_headers": { "type": "boolean" }, "cache_headers_whitelist": { "type": "array", "items": { "type": "string" } }, "cache_based_on_cookies": { "type": "boolean" }, "cache_cookies_whitelist": { "type": "array", "items": { "type": "string" } }, "forward_query_string": { "type": "boolean" }, "forward_query_string_cache_keys": { "type": "array", "items": { "type": "string" } }, "forward_headers": { "type": "array", "items": { "type": "string" } }, "forward_cookies": { "type": "boolean" }, "forward_cookies_whitelist": { "type": "array", "items": { "type": "string" } }, "response_headers_override": { "type": "object", "additionalProperties": { "type": "string" } }, "cors_enabled": { "type": "boolean" }, "cors_origin_whitelist": { "type": "array", "items": { "type": "string" } }, "cors_headers": { "type": "array", "items": { "type": "string" } }, "cors_methods": { "type": "array", "items": { "type": "string" } }, "cors_max_age": { "type": "integer" }, "cors_credentials": { "type": "boolean" }, "index_rewrite": { "type": "boolean", "description": "S3/storage origins only. When true, requests to a path ending in / get index.html appended (static-site index handling)." }, "subdomain_routing": { "type": "boolean", "description": "S3/storage origins only. Multi-tenant wildcard hosting: a viewer-request CloudFront function maps the request subdomain to a bucket folder prefix (abc.domain.com/x.css -> /abc/x.css, abc.domain.com/ -> /abc/index.html). www and the apex map to the bucket root (no prefix). Requires a wildcard SSL cert (*.domain.com) on the custom domain and files laid out as /{subdomain}/... in the bucket. Default false. Can be set on POST /cdn/resource at creation, or turned on later with this PUT (action: update, priority 0). A custom domain outside the wildcard needs its own folder, see the folder field on custom_domains." } } }, "CustomDomainMutationItem": { "type": "object", "required": [ "action" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Required when action is remove" }, "action": { "type": "string", "enum": [ "add", "remove" ] }, "domain_name": { "type": "string", "description": "Required when action is add" }, "additional_domains": { "type": "array", "items": { "type": "string" } }, "certificate_id": { "type": "string", "format": "uuid" }, "folder": { "type": "string", "description": "Bucket folder this hostname serves, on a resource with subdomain_routing. Required before activating the custom domain, since the folder cannot be derived from a domain outside the wildcard. Letters, numbers, dot, dash and underscore only.", "example": "advogado" } } }, "UpdateResourceRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "distribution_domain": { "type": "string" }, "origin_groups": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateResourceOriginGroupItem" } }, "behaviors": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateResourceBehaviorItem" } }, "custom_error_responses": { "type": "array", "items": { "$ref": "#/components/schemas/CustomErrorResponse" } }, "custom_domains": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDomainMutationItem" } } } }, "CustomDomainResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "resource_id": { "type": "string", "format": "uuid" }, "domain_name": { "type": "string" }, "additional_domains": { "type": "array", "items": { "type": "string" } }, "certificate_id": { "type": "string", "format": "uuid" }, "certificate_status": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tenant_distribution_id": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "folder": { "type": "string", "nullable": true, "description": "Bucket folder this hostname serves, on a resource with subdomain_routing. Required before activating the custom domain, since the folder cannot be derived from a domain outside the wildcard. Letters, numbers, dot, dash and underscore only.", "example": "advogado" } } }, "UpdateCustomDomainRequest": { "type": "object", "properties": { "domain_name": { "type": "string" }, "additional_domains": { "type": "array", "items": { "type": "string" } }, "certificate_id": { "type": "string", "format": "uuid" }, "folder": { "type": "string", "description": "Bucket folder this hostname serves, on a resource with subdomain_routing. Required before activating the custom domain, since the folder cannot be derived from a domain outside the wildcard. Letters, numbers, dot, dash and underscore only.", "example": "advogado" } } }, "ResourceResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "origin_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "hostname": { "type": "string" }, "priority": { "type": "integer" } } } }, "distribution_id": { "type": "string" }, "distribution_domain": { "type": "string" }, "custom_error_responses": { "type": "array", "items": { "$ref": "#/components/schemas/CustomErrorResponse" } }, "custom_domains": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDomainResponse" } }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PurgeByUrlRequest": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "subdomain": { "type": "string", "description": "Folder to purge on a resource with subdomain_routing. Required there, because objects are cached under /{folder}/..., so purging the public path alone never matches. Use \"/*\" to purge every tenant.", "example": "advogado" } } }, "PurgeByPatternRequest": { "type": "object", "required": [ "patterns" ], "properties": { "patterns": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "subdomain": { "type": "string", "description": "Folder to purge on a resource with subdomain_routing. Required there, because objects are cached under /{folder}/..., so purging the public path alone never matches. Use \"/*\" to purge every tenant.", "example": "advogado" } } }, "PurgeResponse": { "type": "object", "properties": { "invalidation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "inprogress", "completed" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "PurgeResponseWithPaths": { "allOf": [ { "$ref": "#/components/schemas/PurgeResponse" }, { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string" } } } } ] }, "CheckDistributionNameResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "available": { "type": "boolean" }, "distribution_name": { "type": "string" }, "full_domain": { "type": "string" } } }, "CreateSSLCertificateRequest": { "type": "object", "required": [ "domain_name" ], "properties": { "domain_name": { "type": "string" }, "subject_alternative_names": { "type": "array", "items": { "type": "string" } } } }, "Tag": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "maxLength": 128 }, "value": { "type": "string", "maxLength": 256 } } }, "ImportSSLCertificateRequest": { "type": "object", "required": [ "certificate", "private_key" ], "properties": { "certificate": { "type": "string", "description": "PEM certificate" }, "private_key": { "type": "string", "description": "PEM private key" }, "certificate_chain": { "type": "string", "description": "PEM certificate chain" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }, "SSLCertificateResponse": { "type": "object", "properties": { "certificate_arn": { "type": "string" }, "domain_name": { "type": "string" }, "subject_alternative_names": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "validation_method": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "validation_records": { "type": "array", "items": { "type": "object" } } } }, "File": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique file ID" }, "name": { "type": "string", "description": "File name" }, "description": { "type": "string", "description": "File description" }, "folder_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Folder ID (null if in root)" }, "key_path": { "type": "string", "description": "Base S3 path (without file name)" }, "size": { "type": "integer", "description": "File size in bytes" }, "content_type": { "type": "string", "description": "File MIME type" }, "etag": { "type": "string", "description": "File ETag" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time", "description": "Creation date" }, "updated_at": { "type": "string", "format": "date-time", "description": "Update date" } } }, "UploadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "File created successfully" }, "data": { "$ref": "#/components/schemas/File" } } }, "Bucket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique bucket ID" }, "name": { "type": "string", "description": "Bucket name" }, "size": { "type": "integer", "description": "Total size in bytes" }, "file_count": { "type": "integer", "description": "Number of files in the bucket" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation date" }, "updated_at": { "type": "string", "format": "date-time", "description": "Update date" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID" } } }, "Folder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique folder ID" }, "bucket_id": { "type": "string", "format": "uuid", "description": "Bucket ID" }, "parent_folder_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Parent folder ID (null if in root)" }, "name": { "type": "string", "description": "Folder name" }, "path": { "type": "string", "description": "Full folder path" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time", "description": "Creation date" }, "updated_at": { "type": "string", "format": "date-time", "description": "Update date" } } }, "Credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique credential ID" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID" }, "bucket_id": { "type": "string", "format": "uuid", "description": "Bucket ID" }, "bucket_name": { "type": "string", "description": "Bucket name" }, "iam_user": { "type": "string", "description": "IAM user name" }, "access_key_id": { "type": "string", "description": "Access Key ID" }, "secret_access_key": { "type": "string", "description": "Secret Access Key (only on creation)" }, "prefix": { "type": "string", "description": "Allowed S3 prefix" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation date" } } }, "UploadMetadata": { "type": "object", "required": [ "authorization", "bucket_id", "filename", "filetype" ], "properties": { "authorization": { "type": "string", "description": "Authentication token (JWT Bearer or API Key)", "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "bucket_id": { "type": "string", "format": "uuid", "description": "UUID of the bucket where the file will be stored", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "filename": { "type": "string", "description": "File name", "example": "document.pdf" }, "filetype": { "type": "string", "description": "File MIME type", "example": "application/pdf" }, "folder_id": { "type": "string", "format": "uuid", "description": "UUID of the folder where the file will be stored (optional)", "example": "f1e2d3c4-b5a6-7890-1234-567890abcdef" }, "type": { "type": "string", "enum": [ "video", "audio", "image", "document", "archive", "other" ], "description": "File category (optional)", "example": "document" }, "file_id": { "type": "string", "format": "uuid", "description": "File UUID (used only for updates, optional)", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "UploadStatus": { "type": "object", "properties": { "upload_id": { "type": "string", "format": "uuid", "description": "ID do upload" }, "upload_length": { "type": "integer", "description": "Total file size in bytes" }, "upload_offset": { "type": "integer", "description": "Bytes already uploaded" }, "upload_complete": { "type": "boolean", "description": "Whether the upload is completed" }, "created_at": { "type": "string", "format": "date-time", "description": "Upload creation date" } } }, "CreateApikeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "API key name", "example": "My API Key" } } }, "UpdateUserRequest": { "type": "object", "properties": { "phone": { "type": "string", "description": "User phone number", "example": "+1234567890" }, "image_id": { "type": "string", "description": "User profile image ID", "example": "img_123456789" }, "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" } } }, "ChangePasswordRequest": { "type": "object", "required": [ "current_password", "new_password", "access_token" ], "properties": { "current_password": { "type": "string", "description": "Current password" }, "new_password": { "type": "string", "minLength": 8, "description": "New password (min 8 chars)" }, "access_token": { "type": "string", "description": "AWS Cognito access token" } } }, "AppsPortRange": { "type": "object", "required": [ "from", "to" ], "description": "Dedicated instances only: a port can only belong to one customer per IP.", "properties": { "from": { "type": "integer", "example": 9000 }, "to": { "type": "integer", "example": 9010 }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "example": [ "203.0.113.4/32" ] } } }, "AppsFirewallRule": { "type": "object", "required": [ "port", "allowed_ips" ], "description": "Opens a port to the addresses listed and to nobody else. Ports 80 and 443 are refused here because they are managed automatically. For a managed database this is not optional: with an empty list the engine port stays closed.", "properties": { "port": { "type": "string", "example": "5432" }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "example": [ "203.0.113.4/32" ] } } }, "AppsGitSource": { "type": "object", "description": "Deploy from a connected git repository.", "properties": { "repo": { "type": "string" }, "branch": { "type": "string" }, "path": { "type": "string" } } }, "AppsRegistryAuth": { "type": "object", "description": "Credentials for a private registry. Stored encrypted.", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "AppsMachineSpec": { "type": "object", "description": "What the app size bought.", "properties": { "vcpu": { "type": "integer", "example": 2 }, "memory_gb": { "type": "integer", "example": 4 }, "disk_gb": { "type": "integer", "example": 40 } } }, "AppsDatabaseConnection": { "type": "object", "description": "Returned instead of `machine` for a managed database. The password is not here: it is returned once, at creation, in `app_credentials`. The stored copy is encrypted and cannot be read back, so a lost password is a reset.", "properties": { "engine": { "type": "string", "enum": [ "postgres", "mysql" ] }, "storage_gb": { "type": "number", "example": 0.25 }, "connections": { "type": "integer", "example": 25 }, "host": { "type": "string" }, "port": { "type": "integer", "example": 5432 }, "name": { "type": "string" }, "user": { "type": "string" } } }, "AppsInstance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "short_id": { "type": "string", "example": "rhnvfa0j" }, "name": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "provisioning_running", "running", "stopped", "updating", "updating_running", "deleting", "deleting_running", "deleted", "failed" ] }, "status_reason": { "type": "string", "nullable": true, "description": "Why a failed instance failed, naming the step that failed." }, "size": { "type": "string", "description": "App size or database size." }, "dedicated": { "type": "boolean" }, "machine": { "$ref": "#/components/schemas/AppsMachineSpec" }, "database": { "$ref": "#/components/schemas/AppsDatabaseConnection" }, "app_credentials": { "type": "object", "nullable": true, "description": "Returned once, at creation. Not retrievable afterwards." }, "supports_metrics": { "type": "boolean" }, "custom_domain": { "type": "string", "nullable": true }, "firewall_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AppsFirewallRule" } }, "port_ranges": { "type": "array", "items": { "$ref": "#/components/schemas/AppsPortRange" } }, "region_code": { "type": "string", "nullable": true }, "backup_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "AppsInstanceEnvelope": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/AppsInstance" } } }, "AppsCreateInstance": { "type": "object", "required": [ "name" ], "description": "One of `product`, `docker_image`, `source_s3_key` or `git` is required, and so is `size`.", "properties": { "name": { "type": "string", "example": "minha-api" }, "product": { "type": "string", "description": "Marketplace product name, e.g. wordpress, postgresql, mysql." }, "docker_image": { "type": "string", "description": "Public image, or private with `registry_auth`." }, "source_s3_key": { "type": "string", "description": "Bundle uploaded through POST /app/deploy/upload." }, "git": { "$ref": "#/components/schemas/AppsGitSource" }, "size": { "type": "string", "enum": [ "1vcpu-2gb", "2vcpu-4gb", "4vcpu-8gb", "8vcpu-16gb", "12vcpu-24gb", "256mb", "1gb", "10gb", "25gb", "50gb", "100gb" ] }, "tier": { "type": "string", "enum": [ "small", "medium", "large" ], "deprecated": true }, "dedicated": { "type": "boolean", "default": false, "description": "A machine of its own, filled entirely by this instance. Required for port ranges, priced separately because it costs the whole machine, and refused for a managed database." }, "port_ranges": { "type": "array", "items": { "$ref": "#/components/schemas/AppsPortRange" } }, "region": { "type": "string", "example": "eu-central" }, "container_port": { "type": "integer", "example": 8080 }, "health_check_path": { "type": "string", "example": "/" }, "environment_variables": { "type": "object", "additionalProperties": { "type": "string" } }, "custom_domain": { "type": "string" }, "registry_auth": { "$ref": "#/components/schemas/AppsRegistryAuth" }, "firewall_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AppsFirewallRule" } }, "backup_enabled": { "type": "boolean" }, "backup_frequency_days": { "type": "integer" }, "backup_retention_days": { "type": "integer" } } }, "AppsUpdateInstance": { "type": "object", "properties": { "name": { "type": "string" }, "docker_image": { "type": "string" }, "container_port": { "type": "integer" }, "health_check_path": { "type": "string" }, "environment_variables": { "type": "object", "additionalProperties": { "type": "string" } }, "custom_domain": { "type": "string" }, "registry_auth": { "$ref": "#/components/schemas/AppsRegistryAuth" }, "auto_update": { "type": "boolean" }, "backup_enabled": { "type": "boolean" }, "backup_frequency_days": { "type": "integer" }, "backup_retention_days": { "type": "integer" }, "firewall_rules": { "type": "array", "items": { "$ref": "#/components/schemas/AppsFirewallRule" }, "description": "Rewritten whole: an address left out is an address removed." } } }, "AppsProduct": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string" }, "default_port": { "type": "integer", "nullable": true }, "tiers": { "type": "object", "description": "Sizes this product can be sold at." } } }, "CreateTranscriptRequest": { "type": "object", "description": "Send exactly one of `url` or `uploadKey`.", "properties": { "url": { "type": "string", "format": "uri", "description": "Public http(s) URL of the audio or video. Private and internal addresses are refused.", "example": "https://example.com/class-01.mp4" }, "uploadKey": { "type": "string", "description": "Key returned by POST /v1/transcripts/upload, after the file was PUT to its uploadUrl." }, "language": { "type": "string", "description": "ISO 639-1 code (`pt`, `en`, `es`, ...) or `auto` (default). About 99 languages are supported.", "example": "pt" }, "webhookUrl": { "type": "string", "format": "uri", "description": "Called once with POST `{ \"data\": { \"id\", \"status\" } }` when the transcript ends (done or error). One attempt, no retries: read the result with GET /v1/transcripts/{id}." }, "glossary": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Names and terms that must come out right: `{ \"what it hears\": \"what to write\" }`. Up to 100 entries, 100 characters each. Used as a hint to the model and applied to the text afterwards.", "example": { "niu era": "New Era", "mamute cloud": "MamuteCloud" } }, "diarize": { "type": "boolean", "default": false, "description": "Identify who speaks: each word gets a `speaker`, and the result adds `speakers` and `paragraphs`. Priced at US$ 0.03 per hour of audio instead of 0.02 (charged at the normal price if the speakers cannot be delivered). Up to 3 hours of audio; longer files come back without speakers and with `diarizationError`.", "example": true }, "speakers": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Number of speakers, when you know it. Only with `diarize: true`. Without it the number is detected.", "example": 2 } } }, "Transcript": { "allOf": [ { "$ref": "#/components/schemas/TranscriptSummary" }, { "type": "object", "properties": { "text": { "type": "string", "description": "Only when done. Empty string when the audio has no speech.", "example": "Olá pessoal, aqui é o João Pedro..." }, "words": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptWord" }, "description": "Word timestamps. Inline when the result is up to 4 MB; above that, read them from jsonUrl." }, "speakers": { "type": "integer", "nullable": true, "description": "Only with diarize: how many speakers were found. null when the speakers could not be delivered (see diarizationError).", "example": 2 }, "paragraphs": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TranscriptParagraph" }, "description": "Only with diarize. Inline when the result is up to 4 MB; above that, read them from jsonUrl." }, "diarizationError": { "type": "string", "description": "Only when diarize was asked and the speakers could not be delivered (audio over 3 hours, or a failure). The transcript itself is complete.", "example": "Diarization supports audio up to 3h" }, "vttUrl": { "type": "string", "format": "uri", "description": "WebVTT subtitles. Signed URL valid for 1 hour; ask again for a new one. With diarize, each cue starts with a voice tag such as ``." }, "jsonUrl": { "type": "string", "format": "uri", "description": "Full result (text + words). Signed URL valid for 1 hour." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Results are deleted 7 days after the transcript ends." }, "expired": { "type": "boolean", "description": "True once the result was deleted" } } } ] }, "TranscriptionError": { "type": "object", "properties": { "errCode": { "type": "string", "example": "BadRequest" }, "errMsg": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Send exactly one of url or uploadKey" } } } } }, "TranscriptSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "processing", "done", "error" ] }, "source": { "type": "string", "enum": [ "upload", "url" ] }, "url": { "type": "string", "nullable": true, "description": "The url sent, when the source is a URL" }, "diarize": { "type": "boolean", "description": "Whether speaker identification was asked for" }, "language": { "type": "string", "nullable": true, "description": "Detected ISO code once done; before that, the language asked for (null for auto)", "example": "pt" }, "durationSeconds": { "type": "integer", "nullable": true, "description": "Length of the audio, known once it is decoded", "example": 160 }, "coverage": { "type": "number", "nullable": true, "description": "Share of the audio covered by the transcript, 0 to 1. Null when the audio has no speech.", "example": 0.998 }, "costUsd": { "type": "number", "nullable": true, "description": "What the transcript was charged, in USD (fractions of a cent). Null until it is done and billed.", "example": 0.001 }, "error": { "type": "string", "nullable": true, "description": "Why it failed. Starts with `insufficient_balance:` when the paid balance did not cover the audio." }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "TranscriptUpload": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri", "description": "PUT the file body here (any content type), within expiresIn seconds" }, "uploadKey": { "type": "string", "description": "Send it as uploadKey in POST /v1/transcripts" }, "expiresIn": { "type": "integer", "example": 3600 } } }, "TranscriptionBalance": { "type": "object", "properties": { "totalUsd": { "type": "number", "description": "Balance, trial credit included.", "example": 27.98 }, "reservedUsd": { "type": "number", "description": "Held by transcripts running now; charged or released when each one ends", "example": 0.001 }, "availableUsd": { "type": "number", "description": "What new transcripts can use", "example": 27.979 }, "autoRecharge": { "type": "boolean", "description": "With auto-recharge on, transcripts are never refused for balance" } } }, "TranscriptionAnalytics": { "type": "object", "properties": { "month": { "type": "object", "description": "Current calendar month, UTC", "properties": { "minutes": { "type": "number", "example": 319.8 }, "requests": { "type": "integer", "example": 5 }, "spentUsd": { "type": "number", "nullable": true, "example": 0.001 } } }, "perDay": { "type": "array", "description": "One entry per day of the window, oldest first", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "minutes": { "type": "number" } } } }, "health": { "type": "object", "description": "Last `days` days", "properties": { "days": { "type": "integer", "example": 30 }, "transcripts": { "type": "integer", "example": 86 }, "failed": { "type": "integer", "example": 9 }, "medianSecondsToFinish": { "type": "integer", "nullable": true, "example": 2 }, "p95SecondsToFinish": { "type": "integer", "nullable": true, "example": 65 }, "failureReasons": { "type": "array", "description": "Top 5", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } } } } } } } }, "TranscriptWord": { "type": "object", "properties": { "word": { "type": "string", "example": "pessoal" }, "start": { "type": "number", "description": "Seconds from the start of the audio", "example": 1.24 }, "end": { "type": "number", "example": 1.71 }, "probability": { "type": "number", "description": "0 to 1", "example": 0.93 }, "speaker": { "type": "integer", "description": "Only with diarize. Speaker number from 0, in the order each voice first appears.", "example": 0 } } }, "CreateTranslationRequest": { "type": "object", "description": "Send exactly one of `text`, `vtt` or `transcriptId`.", "required": [ "targets" ], "properties": { "text": { "type": "string", "description": "Plain text, up to 500,000 characters. Line breaks are kept.", "example": "Ola, tudo bem? Hoje vamos falar de vendas." }, "vtt": { "type": "string", "description": "WebVTT document (starting with WEBVTT), up to 1,000,000 characters. Comes back as WebVTT with the same cues and timings." }, "transcriptId": { "type": "string", "format": "uuid", "description": "A done transcription of the same organization, within its 7 days. Comes back as WebVTT." }, "source": { "type": "string", "description": "Language of the input (`pt`, `en`, `pt-BR`, `por_Latn`, ...). Required for text and vtt; for transcriptId it defaults to the transcription's language.", "example": "pt" }, "targets": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" }, "description": "Languages to translate into, unique, none equal to the source", "example": [ "en", "es" ] }, "webhookUrl": { "type": "string", "format": "uri", "description": "Called with POST `{ \"data\": { \"id\", \"status\" } }` when the translation ends (done or error), retried with backoff for about 7 hours while it does not answer 2xx (header `X-Mamute-Webhook-Attempt`)." } } }, "Translation": { "allOf": [ { "$ref": "#/components/schemas/TranslationSummary" }, { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "When the results are deleted (7 days after finishing)" }, "expired": { "type": "boolean", "description": "Present and true once the results are gone" }, "translations": { "type": "array", "description": "Once done, one per target language", "items": { "type": "object", "properties": { "language": { "type": "string", "example": "en" }, "format": { "type": "string", "enum": [ "text", "vtt" ] }, "content": { "type": "string", "description": "The translation, inline while all of them add up to 4 MB; otherwise read it from url" }, "url": { "type": "string", "format": "uri", "description": "Signed link to the file, valid for 1 hour" } } } } } } ] }, "TranslationError": { "type": "object", "properties": { "errCode": { "type": "string", "example": "BadRequest" }, "errMsg": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Send exactly one of text, vtt or transcriptId" } } } } }, "TranslationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "processing", "done", "error" ] }, "format": { "type": "string", "enum": [ "text", "vtt", "transcript" ] }, "transcriptId": { "type": "string", "format": "uuid", "nullable": true }, "source": { "type": "string", "example": "pt" }, "targets": { "type": "array", "items": { "type": "string" }, "example": [ "en", "es" ] }, "characters": { "type": "integer", "nullable": true, "description": "Source characters, known once the input is read", "example": 54210 }, "billedCharacters": { "type": "integer", "nullable": true, "description": "characters x targets, what is charged at US$ 1 per million", "example": 108420 }, "error": { "type": "string", "nullable": true, "description": "Why it failed. Starts with `insufficient_balance:` when the paid balance did not cover it." }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "TranslationBalance": { "type": "object", "properties": { "totalUsd": { "type": "number", "description": "Balance, trial credit included.", "example": 27.98 }, "reservedUsd": { "type": "number", "description": "Held by translations running now; charged or released when each one ends", "example": 0.11 }, "availableUsd": { "type": "number", "description": "What new translations can use", "example": 27.87 }, "autoRecharge": { "type": "boolean", "description": "With auto-recharge on, translations are never refused for balance" } } }, "TranslationAnalytics": { "type": "object", "properties": { "month": { "type": "object", "description": "Current calendar month, UTC", "properties": { "characters": { "type": "integer", "description": "Billed characters of done translations", "example": 1250000 }, "requests": { "type": "integer", "example": 42 }, "spentUsd": { "type": "number", "nullable": true, "example": 1.25 } } }, "perDay": { "type": "array", "description": "One entry per day of the window, oldest first", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "characters": { "type": "integer" }, "jobs": { "type": "integer", "description": "Translations finished on that day" }, "costUsd": { "type": "number", "nullable": true, "description": "Spent on that day, null when billing is off" } } } }, "health": { "type": "object", "description": "Last `days` days", "properties": { "days": { "type": "integer", "example": 30 }, "translations": { "type": "integer", "example": 86 }, "failed": { "type": "integer", "example": 2 }, "medianSecondsToFinish": { "type": "integer", "nullable": true, "example": 3 }, "p95SecondsToFinish": { "type": "integer", "nullable": true, "example": 40 }, "failureReasons": { "type": "array", "description": "Top 5", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } } } } } } } }, "TranscriptSentence": { "type": "object", "properties": { "text": { "type": "string", "example": "Bom dia, pessoal." }, "start": { "type": "number", "example": 0.32 }, "end": { "type": "number", "example": 1.35 } } }, "TranscriptParagraph": { "type": "object", "description": "A run of speech by one speaker. A new paragraph starts when the speaker changes or after a pause longer than 2 seconds.", "properties": { "speaker": { "type": "integer", "example": 0 }, "start": { "type": "number", "example": 0.32 }, "end": { "type": "number", "example": 3.05 }, "numWords": { "type": "integer", "example": 8 }, "sentences": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptSentence" } } } } }, "responses": { "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequest": { "description": "Bad request - validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Validation failed", "code": "VALIDATION_ERROR", "errors": [ "Missing authorization header", "Missing bucket_id in metadata", "Missing filename in metadata", "Missing filetype in metadata", "Invalid metadata format" ] } } } }, "Forbidden": { "description": "Forbidden - insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Insufficient permissions", "code": "FORBIDDEN" } } } }, "Conflict": { "description": "Conflict with existing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequests": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Resource identifier" }, "CustomDomainIdPath": { "name": "customDomainId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Custom domain identifier" }, "BucketId": { "name": "bucketId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique bucket ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "FileId": { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique file ID", "example": "550e8400-e29b-41d4-a716-446655440003" }, "FolderId": { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique folder ID", "example": "550e8400-e29b-41d4-a716-446655440002" } } }, "paths": { "/analytics/stats": { "get": { "tags": [ "Analytics" ], "summary": "Get Analytics Statistics", "description": "Retrieve comprehensive analytics data including traffic patterns, geographic distribution, and performance metrics for data-driven optimization.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/analytics/reports": { "get": { "tags": [ "Analytics" ], "summary": "Generate Analytics Reports", "description": "Generate detailed analytics reports with customizable date ranges, metrics, and export formats for business intelligence and reporting.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/billing/account": { "get": { "tags": [ "Billing" ], "summary": "Get Billing Account", "description": "Retrieve billing account information including payment methods, billing address, and account status for financial management.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] }, "put": { "tags": [ "Billing" ], "summary": "Update Billing Account", "description": "Update billing account details including payment methods, billing address, and notification preferences for invoices.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "Get Usage Statistics", "description": "Retrieve detailed usage statistics across all services including bandwidth consumption, storage usage, and API calls for cost analysis.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "List Invoices", "description": "Retrieve billing invoices with payment status, itemized charges, and downloadable PDF receipts for accounting purposes.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/origin-group/{id}": { "get": { "operationId": "getOriginGroup", "tags": [ "Origin Groups" ], "summary": "Get origin group by ID", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Origin group retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OriginGroupResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateOriginGroup", "tags": [ "Origin Groups" ], "summary": "Update origin group", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOriginGroupRequest" } } } }, "responses": { "200": { "description": "Origin group updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OriginGroupResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource": { "post": { "operationId": "createResource", "tags": [ "Resources" ], "summary": "Create resource", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResourceRequest" } } } }, "responses": { "201": { "description": "Resource created successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResourceResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listResources", "tags": [ "Resources" ], "summary": "List all resources", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Resources retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceResponse" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}": { "get": { "operationId": "getResource", "tags": [ "Resources" ], "summary": "Get resource by ID", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Resource retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResourceResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateResource", "tags": [ "Resources" ], "summary": "Update resource", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateResourceRequest" } } } }, "responses": { "200": { "description": "Resource updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResourceResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteResource", "tags": [ "Resources" ], "summary": "Delete resource", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Resource deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/purge/url": { "post": { "operationId": "purgeByUrl", "tags": [ "Resources" ], "summary": "Purge cache by URL", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeByUrlRequest" } } } }, "responses": { "200": { "description": "Purge initiated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurgeResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/purge/pattern": { "post": { "operationId": "purgeByPattern", "tags": [ "Resources" ], "summary": "Purge cache by pattern", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeByPatternRequest" } } } }, "responses": { "200": { "description": "Purge initiated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurgeResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/purge/all": { "post": { "operationId": "purgeAll", "tags": [ "Resources" ], "summary": "Purge all cache", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Purge initiated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurgeResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/purge/history": { "get": { "operationId": "getPurgeHistory", "tags": [ "Resources" ], "summary": "Get purge history", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Purge history retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurgeResponseWithPaths" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/check-distribution-name": { "get": { "operationId": "checkDistributionNameAvailability", "tags": [ "Resources" ], "summary": "Check distribution name availability", "parameters": [ { "name": "distribution_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Distribution name to check" } ], "responses": { "200": { "description": "Distribution name availability checked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckDistributionNameResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/custom-domain/{customDomainId}": { "put": { "operationId": "updateCustomDomain", "tags": [ "Resources" ], "summary": "Update custom domain in resource", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/CustomDomainIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomDomainRequest" } } } }, "responses": { "200": { "description": "Custom domain updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomDomainResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/custom-domain/{customDomainId}/activate": { "post": { "operationId": "activateCustomDomain", "tags": [ "Resources" ], "summary": "Activate custom domain", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/CustomDomainIdPath" } ], "responses": { "200": { "description": "Custom domain activated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/resource/{id}/custom-domain/{customDomainId}/deactivate": { "post": { "operationId": "deactivateCustomDomain", "tags": [ "Resources" ], "summary": "Deactivate custom domain", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "$ref": "#/components/parameters/CustomDomainIdPath" } ], "responses": { "200": { "description": "Custom domain deactivated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/ssl-certificate": { "post": { "operationId": "createSSLCertificate", "tags": [ "SSL Certificates" ], "summary": "Request a new SSL certificate", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSSLCertificateRequest" } } } }, "responses": { "201": { "description": "Certificate request submitted successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SSLCertificateResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listSSLCertificates", "tags": [ "SSL Certificates" ], "summary": "List all SSL certificates", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Certificates retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SSLCertificateResponse" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/ssl-certificate/import": { "post": { "operationId": "importSSLCertificate", "tags": [ "SSL Certificates" ], "summary": "Import an existing SSL certificate", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSSLCertificateRequest" } } } }, "responses": { "201": { "description": "Certificate imported successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SSLCertificateResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/cdn/ssl-certificate/{id}": { "get": { "operationId": "getSSLCertificate", "tags": [ "SSL Certificates" ], "summary": "Get SSL certificate details", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Certificate details retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SSLCertificateResponse" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteSSLCertificate", "tags": [ "SSL Certificates" ], "summary": "Delete an SSL certificate", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Certificate deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/resource/{resource_id}/token-auth/enable": { "post": { "description": "", "responses": { "200": { "description": "" } }, "parameters": [ { "in": "path", "name": "resource_id", "schema": { "type": "string" }, "required": true } ], "operationId": "post_resource-resource-id-token-auth-enable", "summary": "Enable token auth" } }, "/cdn/resource/{resource_id}/token-auth/disable": { "post": { "description": "", "responses": { "200": { "description": "" } }, "parameters": [ { "in": "path", "name": "resource_id", "schema": { "type": "string" }, "required": true } ], "operationId": "post_cdn-resource-resource-id-token-auth-disable" } }, "/cdn/resource/{resource_id}/signed-url": { "post": { "description": "", "responses": { "200": { "description": "" } }, "parameters": [ { "in": "path", "name": "resource_id", "schema": { "type": "string" }, "required": true } ], "operationId": "post_cdn-resource-resource-id-signed-url", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Full URL of the content to sign" }, "expires_in": { "type": "number", "default": "3600", "description": " Seconds until expiration (e.g. 3600 = 1h)" } }, "required": [ "url" ] }, "examples": { "New Example": { "summary": "New Example", "value": { "url": "https://r-xxxxxxxx.mamutecdn.com/path/to/file.mp4", "expires_in": 3600 } } } } } } } }, "/dns/zones/{zone_id}/records": { "post": { "tags": [ "DNS Records" ], "summary": "Create DNS Record", "description": "Add a new DNS record to the specified zone. Supports all standard record types with automatic validation and conflict detection.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "zone_id", "in": "path", "required": true, "description": "DNS zone identifier", "schema": { "type": "string" } } ] }, "get": { "tags": [ "DNS Records" ], "summary": "List DNS Records", "description": "Retrieve all DNS records for a specific zone. Supports filtering by record type (A, AAAA, CNAME, MX, TXT, NS) and pagination for large record sets.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "zone_id", "in": "path", "required": true, "description": "DNS zone identifier", "schema": { "type": "string" } } ] } }, "/dns/zones/{zone_id}/records/{record_id}": { "get": { "tags": [ "DNS Records" ], "summary": "Get DNS Record", "description": "Retrieve detailed information about a specific DNS record including its current value, TTL settings, and last modification timestamp.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "zone_id", "in": "path", "required": true, "description": "DNS zone identifier", "schema": { "type": "string" } }, { "name": "record_id", "in": "path", "required": true, "description": "DNS record identifier", "schema": { "type": "string" } } ] }, "delete": { "tags": [ "DNS Records" ], "summary": "Delete DNS Record", "description": "Remove a DNS record from the zone. Changes take effect immediately and will stop resolution for the specified record name and type.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "zone_id", "in": "path", "required": true, "description": "DNS zone identifier", "schema": { "type": "string" } }, { "name": "record_id", "in": "path", "required": true, "description": "DNS record identifier", "schema": { "type": "string" } } ] } }, "/dns/records/{record_id}": { "put": { "tags": [ "DNS Records" ], "summary": "Update DNS Record", "description": "Modify an existing DNS record's value, TTL, or other properties. Changes are validated and propagated to all nameservers within minutes.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "parameters": [ { "name": "record_id", "in": "path", "required": true, "description": "DNS record identifier", "schema": { "type": "string" } } ] } }, "/dns/zones": { "post": { "tags": [ "DNS Zones" ], "summary": "Create DNS Zone", "description": "Create a new DNS zone for domain management. Automatically configures nameservers and creates default DNS records for the specified domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "get": { "tags": [ "DNS Zones" ], "summary": "List DNS Zones", "description": "Retrieve all DNS zones associated with your organization. Returns zone details including domain names, status, and configuration settings.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/dns/zones/{id}": { "get": { "tags": [ "DNS Zones" ], "summary": "Get DNS Zone Details", "description": "Retrieve detailed information about a specific DNS zone including all associated records, nameservers, and configuration settings.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier", "schema": { "type": "string" } } ] }, "delete": { "tags": [ "DNS Zones" ], "summary": "Delete DNS Zone", "description": "Permanently delete a DNS zone and all associated records. This action cannot be undone and will immediately stop DNS resolution for the domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier", "schema": { "type": "string" } } ] } }, "/dns/records": { "get": { "tags": [ "DNS Records" ], "summary": "List DNS records", "description": "Get DNS records for a zone", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "DNS Records" ], "summary": "Create DNS record", "description": "Create new DNS record", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/organization/profile": { "get": { "tags": [ "Organization Management" ], "summary": "Get Organization Profile", "description": "Retrieve organization profile information including company details, contact information, and administrative settings.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] }, "put": { "tags": [ "Organization Management" ], "summary": "Update Organization Profile", "description": "Update organization profile information such as company name, address, and administrative contact details.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/organization": { "get": { "tags": [ "Organization Management" ], "summary": "Get Organization Details", "description": "Retrieve comprehensive organization information including member count, subscription details, usage statistics, and billing information.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Organization Management" ], "summary": "Update Organization", "description": "Update organization settings including name, contact information, billing details, and notification preferences.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/health": {}, "/object-storage/buckets": { "get": { "operationId": "listBuckets", "tags": [ "Buckets" ], "summary": "List buckets", "description": "Returns a list of all storage buckets associated with your organization. Requires API token authentication.", "responses": { "200": { "description": "Buckets list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "buckets": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-bucket", "size": 1048576, "file_count": 10, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "organization_id": "550e8400-e29b-41d4-a716-446655440001" } ], "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createBucket", "tags": [ "Buckets" ], "summary": "Create bucket", "description": "Creates a new storage bucket for your organization. Requires API token authentication.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Bucket name (must be unique, lowercase, alphanumeric and hyphens, minimum 3 characters)", "example": "my-bucket" } } }, "example": { "name": "my-bucket" } } } }, "responses": { "201": { "description": "Bucket created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Bucket created successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-bucket", "size": 0, "file_count": 0, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "organization_id": "550e8400-e29b-41d4-a716-446655440001" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Bucket already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Bucket already exists", "code": "BUCKET_ALREADY_EXISTS" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}": { "get": { "operationId": "getBucket", "tags": [ "Buckets" ], "summary": "Get bucket details", "description": "Retrieves detailed information about a specific bucket. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "responses": { "200": { "description": "Bucket details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-bucket", "size": 1048576, "file_count": 10, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "organization_id": "550e8400-e29b-41d4-a716-446655440001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateBucket", "tags": [ "Buckets" ], "summary": "Update bucket", "description": "Updates the name of an existing bucket. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New bucket name", "example": "my-updated-bucket" } } }, "example": { "name": "my-updated-bucket" } } } }, "responses": { "200": { "description": "Bucket updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Bucket updated successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "my-updated-bucket", "size": 1048576, "file_count": 10, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "organization_id": "550e8400-e29b-41d4-a716-446655440001" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Bucket name is already in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Bucket name already in use", "code": "BUCKET_NAME_CONFLICT" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteBucket", "tags": [ "Buckets" ], "summary": "Delete bucket", "description": "Permanently deletes a bucket and all files and folders contained within it. This action cannot be undone. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "responses": { "200": { "description": "Bucket deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Bucket deleted successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/files": { "get": { "operationId": "listFiles", "tags": [ "Files" ], "summary": "List files", "description": "Returns a paginated list of files in a specific bucket with optional filtering. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page (maximum 1000)", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 1000, "minimum": 1 }, "example": 50 }, { "name": "folder_id", "in": "query", "description": "Filter files by folder ID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440002" }, { "name": "filename", "in": "query", "description": "Filter files by name (partial search)", "required": false, "schema": { "type": "string" }, "example": "image" } ], "responses": { "200": { "description": "Files list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "files": [ { "id": "550e8400-e29b-41d4-a716-446655440003", "name": "image.jpg", "description": "My image", "folder_id": "550e8400-e29b-41d4-a716-446655440002", "key_path": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "John Doe" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } ], "total": 1, "page": 1, "limit": 50, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createFile", "tags": [ "Files" ], "summary": "Create file", "description": "Creates a new file record in the bucket. This endpoint registers file metadata in the system. The actual file upload to S3 should be done separately using S3 credentials or presigned URLs. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "size", "content_type" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique file ID", "example": "550e8400-e29b-41d4-a716-446655440003" }, "name": { "type": "string", "description": "File name", "example": "image.jpg" }, "folder_id": { "type": "string", "format": "uuid", "description": "Folder ID (optional)", "example": "550e8400-e29b-41d4-a716-446655440002" }, "description": { "type": "string", "description": "File description", "example": "My image" }, "size": { "type": "integer", "description": "File size in bytes", "example": 1048576 }, "content_type": { "type": "string", "description": "File MIME type", "example": "image/jpeg" }, "etag": { "type": "string", "description": "File ETag (optional)", "example": "abc123def456" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": { "type": "string" }, "example": { "author": "John Doe" } } } }, "example": { "id": "550e8400-e29b-41d4-a716-446655440003", "name": "image.jpg", "folder_id": "550e8400-e29b-41d4-a716-446655440002", "description": "My image", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "John Doe" } } } } }, "responses": { "201": { "description": "File created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "File created successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440003", "name": "image.jpg", "description": "My image", "folder_id": "550e8400-e29b-41d4-a716-446655440002", "key_path": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "John Doe" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "File already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "File already exists", "code": "FILE_ALREADY_EXISTS" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/files/{fileId}": { "get": { "operationId": "getFile", "tags": [ "Files" ], "summary": "Get file details", "description": "Retrieves detailed information about a specific file including metadata, size, location, and timestamps. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FileId" } ], "responses": { "200": { "description": "File details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440003", "name": "image.jpg", "description": "My image", "folder_id": "550e8400-e29b-41d4-a716-446655440002", "key_path": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "John Doe" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateFile", "tags": [ "Files" ], "summary": "Update file", "description": "Updates file metadata including name, description, folder location, and custom metadata. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FileId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New file name", "example": "new-image.jpg" }, "folder_id": { "type": "string", "format": "uuid", "description": "Destination folder ID (to move file)", "example": "550e8400-e29b-41d4-a716-446655440004" }, "description": { "type": "string", "description": "New file description", "example": "Updated image" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": { "type": "string" }, "example": { "author": "Jane Doe" } } } }, "example": { "name": "new-image.jpg", "folder_id": "550e8400-e29b-41d4-a716-446655440004", "description": "Updated image", "metadata": { "author": "Jane Doe" } } } } }, "responses": { "200": { "description": "File updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "File updated successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440003", "name": "new-image.jpg", "description": "Updated image", "folder_id": "550e8400-e29b-41d4-a716-446655440004", "key_path": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "Jane Doe" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict (e.g., name already exists in destination folder)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "File name already exists in destination folder", "code": "FILE_NAME_CONFLICT" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete file", "description": "Permanently deletes a file from the bucket. This action cannot be undone. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FileId" } ], "responses": { "200": { "description": "File deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "File deleted successfully" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/files/{fileId}/download": { "get": { "operationId": "getDownloadUrl", "tags": [ "Files" ], "summary": "Get download URL", "description": "Generates a presigned URL for secure file download. The URL provides temporary access to the file without requiring authentication. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FileId" }, { "name": "expires_in", "in": "query", "description": "URL expiration time in seconds (1-604800, default 300)", "required": false, "schema": { "type": "integer", "default": 300, "minimum": 1, "maximum": 604800 }, "example": 3600 } ], "responses": { "200": { "description": "Download URL generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "download_url": "https://s3.amazonaws.com/bucket/file.jpg?X-Amz-Algorithm=...", "expires_at": "2024-01-01T01:00:00.000Z", "expires_in": 3600 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/files/{fileId}/copy": { "post": { "operationId": "copyFile", "tags": [ "Files" ], "summary": "Copy file", "description": "Creates a copy of an existing file in the same or different folder location. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FileId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID for the new file", "example": "550e8400-e29b-41d4-a716-446655440005" }, "destination_folder_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Destination folder ID (null for root)", "example": "550e8400-e29b-41d4-a716-446655440004" }, "new_name": { "type": "string", "description": "New name for the copied file (optional)", "example": "image-copy.jpg" }, "metadata": { "type": "object", "description": "Custom metadata for the copied file", "additionalProperties": { "type": "string" }, "example": { "author": "John Doe" } } } }, "example": { "id": "550e8400-e29b-41d4-a716-446655440005", "destination_folder_id": "550e8400-e29b-41d4-a716-446655440004", "new_name": "image-copy.jpg", "metadata": { "author": "John Doe" } } } } }, "responses": { "201": { "description": "File copied successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "File copied successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440005", "name": "image-copy.jpg", "description": "My image", "folder_id": "550e8400-e29b-41d4-a716-446655440004", "key_path": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "size": 1048576, "content_type": "image/jpeg", "etag": "abc123def456", "metadata": { "author": "John Doe" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "File with same name already exists in destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "File with same name already exists in destination", "code": "FILE_NAME_CONFLICT" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/folders": { "get": { "operationId": "listFolders", "tags": [ "Folders" ], "summary": "List folders", "description": "Returns a list of folders in a bucket, optionally filtered by parent folder. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "name": "parent_folder_id", "in": "query", "description": "Filter folders by parent folder ID (null for root)", "required": false, "schema": { "type": "string", "format": "uuid", "nullable": true }, "example": "550e8400-e29b-41d4-a716-446655440002" } ], "responses": { "200": { "description": "Folders list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "folders": [ { "id": "550e8400-e29b-41d4-a716-446655440002", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "parent_folder_id": null, "name": "documents", "path": "/documents", "metadata": { "description": "Documents folder" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } ], "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createFolder", "tags": [ "Folders" ], "summary": "Create folder", "description": "Creates a new folder in the bucket for organizing files. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Folder name", "example": "documents" }, "parent_folder_id": { "type": "string", "format": "uuid", "description": "Parent folder ID (optional, to create subfolder)", "example": "550e8400-e29b-41d4-a716-446655440002" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": true, "example": { "description": "Documents folder" } } } }, "example": { "name": "documents", "parent_folder_id": null, "metadata": { "description": "Documents folder" } } } } }, "responses": { "201": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Folder created successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440002", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "parent_folder_id": null, "name": "documents", "path": "/documents", "metadata": { "description": "Documents folder" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Folder already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Folder already exists", "code": "FOLDER_ALREADY_EXISTS" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/folders/{folderId}": { "get": { "operationId": "getFolder", "tags": [ "Folders" ], "summary": "Get folder details", "description": "Retrieves detailed information about a specific folder including its path, parent relationship, and metadata. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FolderId" } ], "responses": { "200": { "description": "Folder details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440002", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "parent_folder_id": null, "name": "documents", "path": "/documents", "metadata": { "description": "Documents folder" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateFolder", "tags": [ "Folders" ], "summary": "Update folder", "description": "Updates folder information including name, parent folder (to move folder), and metadata. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FolderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New folder name", "example": "updated-documents" }, "parent_folder_id": { "type": "string", "format": "uuid", "description": "New parent folder ID (to move folder)", "example": "550e8400-e29b-41d4-a716-446655440004" }, "metadata": { "type": "object", "description": "Custom metadata", "additionalProperties": true, "example": { "description": "Updated folder" } } } }, "example": { "name": "updated-documents", "parent_folder_id": null, "metadata": { "description": "Updated folder" } } } } }, "responses": { "200": { "description": "Folder updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Folder updated successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440002", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "parent_folder_id": null, "name": "updated-documents", "path": "/updated-documents", "metadata": { "description": "Updated folder" }, "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict (e.g., name already exists in destination folder)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Folder name already exists in destination", "code": "FOLDER_NAME_CONFLICT" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteFolder", "tags": [ "Folders" ], "summary": "Delete folder", "description": "Permanently deletes a folder and all files and subfolders contained within it. This action cannot be undone. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "$ref": "#/components/parameters/FolderId" } ], "responses": { "200": { "description": "Folder deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Folder deleted successfully" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/credentials": { "get": { "operationId": "listCredentials", "tags": [ "Credentials" ], "summary": "List credentials", "description": "Returns a list of S3 access credentials (IAM users and access keys) associated with a bucket. These credentials can be used for direct S3 access via AWS CLI, SDKs, or other S3-compatible tools. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "responses": { "200": { "description": "Credentials list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "data": { "credentials": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "organization_id": "550e8400-e29b-41d4-a716-446655440001", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "bucket_name": "my-bucket", "iam_user": "mamutecdn-bucket-550e8400", "access_key_id": "AKIAIOSFODNN7EXAMPLE", "prefix": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-01T00:00:00.000Z" } ], "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createCredentials", "tags": [ "Credentials" ], "summary": "Create S3 credentials", "description": "Creates S3 access credentials (IAM user and access keys) for programmatic access to the bucket. These credentials allow direct access to S3 storage using AWS CLI, SDKs, or other S3-compatible tools. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" } ], "responses": { "201": { "description": "Credentials created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Credentials created successfully", "data": { "id": "550e8400-e29b-41d4-a716-446655440006", "organization_id": "550e8400-e29b-41d4-a716-446655440001", "bucket_id": "550e8400-e29b-41d4-a716-446655440000", "bucket_name": "my-bucket", "iam_user": "mamutecdn-bucket-550e8400", "access_key_id": "AKIAIOSFODNN7EXAMPLE", "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "prefix": "organizations/550e8400-e29b-41d4-a716-446655440001/550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-01T00:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Credentials already exist for this bucket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Credentials already exist for this bucket", "code": "CREDENTIALS_ALREADY_EXIST" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/object-storage/buckets/{bucketId}/credentials/{accessKeyId}": { "delete": { "operationId": "revokeCredential", "tags": [ "Credentials" ], "summary": "Revoke credential", "description": "Permanently revokes S3 access credentials by deleting the IAM user and removing credentials from the database. This action cannot be undone. Requires API token authentication.", "parameters": [ { "$ref": "#/components/parameters/BucketId" }, { "name": "accessKeyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Access Key ID of the credential to be revoked", "example": "AKIAIOSFODNN7EXAMPLE" } ], "responses": { "200": { "description": "Credential revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "success": true, "message": "Credential revoked successfully" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/files/": { "post": { "operationId": "createUpload", "tags": [ "Uploads" ], "summary": "Create new upload", "description": "Initiates a new upload using the TUS protocol. This endpoint creates an upload session and returns the URL where file chunks should be sent.\n\n**Required Metadata:**\nAll metadata fields must be base64 encoded and sent in the `Upload-Metadata` header.\n\n- `authorization`: Authentication token\n- `bucket_id`: UUID of the bucket where the file will be stored\n- `filename`: File name\n- `filetype`: MIME type of the file\n\n**Optional Metadata:**\n- `folder_id`: UUID of the folder where the file will be stored\n- `type`: File category (video, audio, image, document, archive, other)\n", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "Upload-Length", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Total file size in bytes" }, { "name": "Upload-Metadata", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 encoded metadata in the format: `key1 base64value1,key2 base64value2`\n\nExample: `filename dGVzdC5wZGY=,filetype YXBwbGljYXRpb24vcGRm,bucket_id YnVja2V0LXV1aWQ=,authorization QmVhcmVyIHRva2Vu`\n", "example": "filename dGVzdC5wZGY=,filetype YXBwbGljYXRpb24vcGRm,bucket_id YnVja2V0LXV1aWQ=,authorization QmVhcmVyIHRva2Vu" }, { "name": "Tus-Resumable", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1.0.0" ], "default": "1.0.0" }, "description": "TUS protocol version" } ], "responses": { "201": { "description": "Upload created successfully", "headers": { "Location": { "description": "URL to continue the upload", "schema": { "type": "string", "example": "/files/550e8400-e29b-41d4-a716-446655440000" } }, "Tus-Resumable": { "description": "Supported TUS protocol version", "schema": { "type": "string", "example": "1.0.0" } }, "Upload-Expires": { "description": "Upload expiration date (optional)", "schema": { "type": "string", "format": "date-time" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Upload created successfully" } } }, "example": { "message": "Upload created successfully" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "File too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "File size exceeds maximum allowed size", "code": "FILE_TOO_LARGE" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/files/{upload_id}": { "head": { "operationId": "getUploadStatus", "tags": [ "Uploads" ], "summary": "Get upload status", "description": "Returns information about the status of an ongoing upload, including current progress.\n", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID do upload retornado no header Location" }, { "name": "Tus-Resumable", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1.0.0" ], "default": "1.0.0" }, "description": "TUS protocol version" } ], "responses": { "200": { "description": "Upload status retrieved successfully", "headers": { "Upload-Length": { "description": "Total file size in bytes", "schema": { "type": "integer", "example": 1048576 } }, "Upload-Offset": { "description": "Bytes already uploaded", "schema": { "type": "integer", "example": 524288 } }, "Tus-Resumable": { "description": "TUS protocol version", "schema": { "type": "string", "example": "1.0.0" } }, "Cache-Control": { "description": "Cache control", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_length": { "type": "integer", "example": 1048576 }, "upload_offset": { "type": "integer", "example": 524288 }, "upload_complete": { "type": "boolean", "example": false } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "uploadChunk", "tags": [ "Uploads" ], "summary": "Upload file chunk", "description": "Sends a chunk (piece) of the file. This endpoint can be called multiple times to send the file in parts.\n\n**Resumable Upload:**\nIf the upload is interrupted, you can resume from where you left off using the `Upload-Offset` header returned by the HEAD endpoint.\n", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "ID do upload retornado no header Location" }, { "name": "Upload-Offset", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Offset in bytes where to start the upload (0 for new upload, or value returned by HEAD to resume)", "example": 0 }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/offset+octet-stream" ], "default": "application/offset+octet-stream" }, "description": "Content type for chunk uploads" }, { "name": "Tus-Resumable", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1.0.0" ], "default": "1.0.0" }, "description": "TUS protocol version" } ], "requestBody": { "required": true, "description": "File chunk in bytes", "content": { "application/offset+octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "204": { "description": "Chunk uploaded successfully", "headers": { "Upload-Offset": { "description": "New offset after chunk upload", "schema": { "type": "integer", "example": 524288 } }, "Tus-Resumable": { "description": "TUS protocol version", "schema": { "type": "string", "example": "1.0.0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Incorrect offset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Upload offset mismatch", "code": "OFFSET_MISMATCH" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict - upload already completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Upload already completed", "code": "UPLOAD_COMPLETED" } } } }, "413": { "description": "Chunk too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "message": "Chunk size exceeds maximum allowed", "code": "CHUNK_TOO_LARGE" } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "cancelUpload", "tags": [ "Uploads" ], "summary": "Cancel upload", "description": "Cancels an ongoing upload. Removes all temporary data associated with the upload.\n", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "upload_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Upload ID to be cancelled" }, { "name": "Tus-Resumable", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "1.0.0" ], "default": "1.0.0" }, "description": "TUS protocol version" } ], "responses": { "204": { "description": "Upload cancelled successfully" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/security/apikey": { "get": { "tags": [ "API Keys" ], "summary": "Get API Key", "description": "Retrieve the current API key for programmatic access to MamuteCDN services. Returns key metadata without exposing the actual key value.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "tags": [ "API Keys" ], "summary": "Generate API Key", "description": "Generate a new API key for programmatic access. Previous keys are automatically revoked. Store the returned key securely as it cannot be retrieved again.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApikeyRequest" } } } } }, "delete": { "tags": [ "API Keys" ], "summary": "Revoke API Key", "description": "Permanently revoke the current API key. All applications using this key will immediately lose access to the API.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/user/profile": { "get": { "tags": [ "User Management" ], "summary": "Get User Profile", "description": "Retrieve the authenticated user's profile information including personal details, organization membership, and account settings.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] }, "put": { "tags": [ "User Management" ], "summary": "Update User Profile", "description": "Update user profile information such as name, phone number, and profile image. Changes are immediately reflected across all services.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } } } }, "/user/change-password": { "post": { "tags": [ "User Management" ], "summary": "Change Password", "description": "Update the user's account password with proper validation. Requires current password verification and enforces strong password policies.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } } } }, "/user/mfa/enable": { "post": { "tags": [ "Multi-Factor Authentication" ], "summary": "Enable Multi-Factor Authentication", "description": "Enable MFA for enhanced account security. Supports TOTP (authenticator apps) and SMS-based verification methods.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/user/mfa/disable": { "post": { "tags": [ "Multi-Factor Authentication" ], "summary": "Disable Multi-Factor Authentication", "description": "Disable MFA for the user account. Requires verification code confirmation to prevent unauthorized changes.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/app/instance": { "post": { "tags": [ "Apps" ], "summary": "Create an instance", "description": "Creates an app or a managed database, depending on the product. The response comes back immediately with `status: provisioning`; provisioning continues in the background and `status_reason` names the step if it fails.\n\nA managed database returns its password once here, in `app_credentials`, and never again. It also needs `firewall_rules`: the engine port stays closed until an address is allowed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsCreateInstance" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid size, invalid firewall rule, or a database size on an app product" }, "401": { "description": "Authentication required" }, "402": { "description": "Refused by billing: no balance, or no price configured for the size in this environment" }, "403": { "description": "Insufficient balance. Trial balance cannot be used for app instances." } } }, "get": { "tags": [ "Apps" ], "summary": "List instances", "responses": { "200": { "description": "Instances of the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppsInstance" } } } } } } }, "401": { "description": "Authentication required" } } } }, "/app/instance/{id}": { "get": { "tags": [ "Apps" ], "summary": "Get an instance", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "404": { "description": "Instance not found" } } }, "put": { "tags": [ "Apps" ], "summary": "Update an instance", "description": "Changing image, port, environment variables or registry auth triggers a redeploy.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsUpdateInstance" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "404": { "description": "Instance not found" } } }, "delete": { "tags": [ "Apps" ], "summary": "Delete an instance", "description": "Removes the container or, for a managed database, drops the database, the role, the disk quota, the firewall rule and the DNS record. Billing stops at deletion.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletion started" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/stop": { "post": { "tags": [ "Apps" ], "summary": "Stop an instance", "description": "Scales the service to zero. A managed database has its CONNECT revoked and open sessions dropped.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/start": { "post": { "tags": [ "Apps" ], "summary": "Start an instance", "description": "Brings a stopped instance back.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/redeploy": { "post": { "tags": [ "Apps" ], "summary": "Redeploy", "description": "Pulls the image again and replaces the running container.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/retry": { "post": { "tags": [ "Apps" ], "summary": "Retry provisioning", "description": "Resumes a failed instance from the step that failed, rather than starting over.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/upgrade": { "post": { "tags": [ "Apps" ], "summary": "Resize", "description": "Moves the instance to another size on the same ladder. A database grows disk and connection limit with no downtime.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "size" ], "properties": { "size": { "type": "string", "enum": [ "1vcpu-2gb", "2vcpu-4gb", "4vcpu-8gb", "8vcpu-16gb", "12vcpu-24gb", "256mb", "1gb", "10gb", "25gb", "50gb", "100gb" ] }, "tier": { "type": "string", "deprecated": true } } } } } } } }, "/app/instance/{id}/upgrade-version": { "post": { "tags": [ "Apps" ], "summary": "Upgrade the product version", "description": "Marketplace products only.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "example": "1.2.0" } } } } } } } }, "/app/instance/{id}/backup": { "post": { "tags": [ "Apps" ], "summary": "Create a backup now", "description": null, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/backups": { "get": { "tags": [ "Apps" ], "summary": "List backups", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshots available to restore" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/restore": { "post": { "tags": [ "Apps" ], "summary": "Restore a backup", "description": "The instance has to be stopped first.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppsInstanceEnvelope" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Instance not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "snapshot_id" ], "properties": { "snapshot_id": { "type": "string" } } } } } } } }, "/app/instance/{id}/logs": { "get": { "tags": [ "Apps" ], "summary": "Container logs", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } }, { "name": "tail", "in": "query", "schema": { "type": "string", "default": "100" } }, { "name": "since", "in": "query", "schema": { "type": "string", "example": "10m" } } ], "responses": { "200": { "description": "Log lines" }, "404": { "description": "Instance not found" } } } }, "/app/instance/{id}/containers": { "get": { "tags": [ "Apps" ], "summary": "Containers of the instance", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Containers and their state" } } } }, "/app/instance/{id}/metrics": { "get": { "tags": [ "Apps" ], "summary": "CPU and memory usage", "description": "Available where the instance runs on our own machines (`supports_metrics: true`).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Instance id (uuid) or short_id", "schema": { "type": "string" } }, { "name": "minutes", "in": "query", "schema": { "type": "integer", "default": 180, "minimum": 5, "maximum": 10080 } } ], "responses": { "200": { "description": "Time series" } } } }, "/app/deploy/upload": { "post": { "tags": [ "Apps" ], "summary": "Presigned URL for a source bundle", "description": "Returns a URL to PUT a .tar.gz and the `source_s3_key` to send back in POST /app/instance. The URL expires in 15 minutes.", "responses": { "200": { "description": "Upload target", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": "string" }, "source_s3_key": { "type": "string" } } } } } } } } }, "/app/marketplace": { "get": { "tags": [ "Marketplace" ], "summary": "List products", "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppsProduct" } } } } } } } } } }, "/app/marketplace/{id}": { "get": { "tags": [ "Marketplace" ], "summary": "Get a product", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product" }, "404": { "description": "Product not found" } } } }, "/v1/transcripts": { "post": { "tags": [ "Transcription" ], "summary": "Create a transcript", "description": "Transcribes an audio or video file, from a public URL or from a file sent with POST /v1/transcripts/upload.\n\nThe call waits up to about 20 seconds: a short file comes back `200` with `status: \"done\"` and the text. Anything longer answers `202` with `status: \"queued\"` or `\"processing\"`; read the result with GET /v1/transcripts/{id} or receive it on `webhookUrl`. Send `?wait=false` to always answer at once.\n\nPricing: US$ 0.02 per hour of audio (US$ 0.03 with `diarize: true`, speaker identification), charged per started minute of the audio actually transcribed, only when the transcript is done. Failed transcripts are not charged. Requires balance (trial credit included) or auto-recharge. The price of each transcript is held from the balance once its length is known, before it is processed: a transcript the balance cannot cover ends in `error` with `insufficient_balance: ...` and costs nothing.\n\nLimits: files up to 2 GB and 6 hours of audio. Results are kept for 7 days.", "parameters": [ { "name": "wait", "in": "query", "required": false, "description": "`false` answers at once with the transcript queued", "schema": { "type": "string", "enum": [ "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranscriptRequest" } } } }, "responses": { "200": { "description": "Finished within the wait", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transcript" } } } } } }, "202": { "description": "Accepted, still running", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transcript" } } } } } }, "400": { "description": "Invalid body (missing url/uploadKey, bad language, glossary over the limits, diarize not a boolean, speakers outside 1-20 or without diarize, private URL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "402": { "description": "No paid balance and no auto-recharge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] }, "get": { "tags": [ "Transcription" ], "summary": "List transcripts", "description": "Newest first. Page with `before`: send the `nextBefore` of the previous page; it is null on the last page.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "`processing` covers queued and processing; `failed` is status error", "schema": { "type": "string", "enum": [ "done", "processing", "failed" ] } }, { "name": "before", "in": "query", "required": false, "description": "createdAt of the last item of the previous page (ISO 8601)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptSummary" } }, "nextBefore": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "400": { "description": "Invalid status or before", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/transcripts/upload": { "post": { "tags": [ "Transcription" ], "summary": "Get an upload URL", "description": "For local files. PUT the file body to `uploadUrl` (valid for 1 hour, up to 2 GB), then create the transcript with `{ \"uploadKey\": \"...\" }`.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranscriptUpload" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/transcripts/{id}": { "get": { "tags": [ "Transcription" ], "summary": "Get a transcript", "description": "Status and, once done, the text, the word timestamps and the subtitle files.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Transcript" } } } } } }, "400": { "description": "Invalid id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/transcripts/balance": { "get": { "tags": [ "Transcription" ], "summary": "Transcription balance", "description": "Paid balance, what running transcripts hold of it, and what is left for new ones.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranscriptionBalance" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "404": { "description": "Billing account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/transcripts/analytics": { "get": { "tags": [ "Transcription" ], "summary": "Transcription analytics", "description": "Minutes, requests and spend this month, minutes per day, and the health of recent transcripts.", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Window for perDay and health", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranscriptionAnalytics" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/translations": { "post": { "tags": [ "Translation" ], "summary": "Create a translation", "description": "Translates plain text, a WebVTT subtitle, or a MamuteCloud transcription into up to 10 languages.\n\nThe call waits up to about 20 seconds: a short text comes back `200` with `status: \"done\"` and the translations. Anything longer answers `202` with `status: \"queued\"` or `\"processing\"`; read the result with GET /v1/translations/{id} or receive it on `webhookUrl`. Send `?wait=false` to always answer at once.\n\nText keeps its line breaks. WebVTT keeps every cue and its timing: cues that split a sentence are translated together and the translation is spread back over them. With `transcriptId` the transcription's WebVTT is translated and its detected language is the source.\n\nPricing: US$ 1 per million characters, per target language: `billedCharacters` = source characters (spaces count; for WebVTT only the cue text, without timings or tags) x number of targets. Charged only when the translation is done; failed translations are not charged. Requires balance (trial credit included) or auto-recharge. The price is held from the balance once the characters are counted: a translation the balance cannot cover ends in `error` with `insufficient_balance: ...` and costs nothing.\n\nLimits: text up to 500,000 characters, WebVTT up to 1,000,000, 10 targets per job. Results are kept for 7 days.", "parameters": [ { "name": "wait", "in": "query", "required": false, "description": "`false` answers at once with the translation queued", "schema": { "type": "string", "enum": [ "false" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranslationRequest" } } } }, "responses": { "200": { "description": "Finished within the wait", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Translation" } } } } } }, "202": { "description": "Accepted, still running", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Translation" } } } } } }, "400": { "description": "Invalid body (not exactly one of text, vtt or transcriptId; unknown language; target equal to the source; over the limits; private webhook URL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "402": { "description": "No paid balance and no auto-recharge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "403": { "description": "Account not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] }, "get": { "tags": [ "Translation" ], "summary": "List translations", "description": "The organization's translations, newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "done", "processing", "failed" ] } }, { "name": "before", "in": "query", "required": false, "description": "`nextBefore` of the previous page", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationSummary" } }, "nextBefore": { "type": "string", "format": "date-time", "nullable": true, "description": "Pass as `before` for the next page; null on the last one" } } } } } }, "400": { "description": "Invalid status or before", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/translations/languages": { "get": { "tags": [ "Translation" ], "summary": "Translation languages", "description": "Codes accepted in `source` and `targets`. ISO 639-1 codes are listed; region codes (`pt-BR`, `zh-TW` for Traditional Chinese) and any of the 202 FLORES-200 codes of the model (`por_Latn`) are accepted too.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "pt" }, "nllb": { "type": "string", "description": "FLORES-200 code", "example": "por_Latn" } } } } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/translations/{id}": { "get": { "tags": [ "Translation" ], "summary": "Get a translation", "description": "Status and, once done, one translation per target language.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Translation" } } } } } }, "400": { "description": "Invalid id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/translations/balance": { "get": { "tags": [ "Translation" ], "summary": "Translation balance", "description": "Paid balance, what running translations hold of it, and what is left for new ones.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslationBalance" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "404": { "description": "Billing account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } }, "/v1/translations/analytics": { "get": { "tags": [ "Translation" ], "summary": "Translation analytics", "description": "Billed characters, requests and spend this month, characters per day, and the health of recent translations.", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Window for perDay and health", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslationAnalytics" } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationError" } } } } }, "security": [ { "apiKey": [] }, { "bearerAuth": [] } ] } } }, "tags": [ { "name": "Apps", "description": "Container instances and managed databases" }, { "name": "Marketplace", "description": "Products available to deploy" }, { "name": "Transcription" }, { "name": "Translation" } ] }