# MamuteCloud API — Full Reference > Complete API reference for MamuteCloud. Each endpoint includes method, path, parameters, request body schema, and response schemas. This file is a superset of the human docs at https://docs.mamutecloud.com. ## Base URLs - Management API: `https://api.mamutecloud.com` (CDN, DNS, SSL, Storage admin, IAM, Organization, Analytics) - S3 data plane (object storage): `https://s3-us-east-1.mamutecloud.com` (path-style, region `us-east-1`) - CDN distribution domains (public site URLs): `https://.mamutecdn.com` - Dashboard: `https://dashboard.mamutecloud.com` - Machine-readable OpenAPI spec: `https://mamutecloud.com/openapi.json` (48 endpoints, all services) - MCP server (Model Context Protocol): `https://docs.mamutecloud.com/mcp` (streamable-http). Exposes tools `list-specs`, `list-endpoints`, `search-endpoints`, `get-endpoint`, `get-server-variables`, and `execute-request` (runs live API calls). Add to an MCP client, e.g. `claude mcp add --transport http mamutecloud https://docs.mamutecloud.com/mcp`. ## Authentication Two authentication models coexist on MamuteCloud: 1. **Management API** (everything documented in this file: CDN, DNS, SSL, Storage admin, IAM, Organization, Analytics) — authenticate with either: - `Authorization: Bearer ` (dashboard-issued user token), or - `Authorization: ` (the key starts with `mamute-`) (programmatic access). Create a key with `POST /security/apikey` and body `{"name": "my-app-key"}` (the `name` field is required). 2. **S3 data plane** (object PUT/GET/LIST/DELETE) — authenticate with an Access Key ID + Secret Access Key pair scoped to a specific bucket. Generate the pair via `POST /object-storage/buckets/{bucketId}/credentials` from the management API, then use any standard AWS S3 SDK (boto3, aws-sdk-js, aws-sdk-go, etc.) configured with: - `endpoint`: `https://s3-us-east-1.mamutecloud.com` - `region`: `us-east-1` - path-style addressing enabled (`forcePathStyle: true` / `s3.addressing_style = path`) - the access key + secret from the step above Object public URL (direct): `https://s3-us-east-1.mamutecloud.com//`. ## Deploy a Static Site (end-to-end) Goal: publish a static site (e.g. `index.html`) to a public URL. Full recipe an agent can follow linearly: ```bash # 1. Create an API key (one-time). Authenticate with your dashboard JWT. curl -X POST https://api.mamutecloud.com/security/apikey \ -H "Authorization: Bearer $JWT" \ -H "content-type: application/json" \ -d '{"name": "deploy-key"}' # -> returns the API key. Store as $MAMUTECLOUD_API_KEY. # 2. Create a storage bucket. curl -X POST https://api.mamutecloud.com/object-storage/buckets \ -H "Authorization: $MAMUTECLOUD_API_KEY" \ -H "content-type: application/json" \ -d '{"name": "my-site", "storage_class": "Standard"}' # -> returns bucket { id }. Store as $BUCKET_ID. # 3. Generate S3 credentials scoped to that bucket. curl -X POST "https://api.mamutecloud.com/object-storage/buckets/$BUCKET_ID/credentials" \ -H "Authorization: $MAMUTECLOUD_API_KEY" \ -H "content-type: application/json" # -> returns { access_key_id, secret_access_key }. The secret is shown once. ``` ```js // 4. Upload index.html with any S3 SDK (Node example). import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; const s3 = new S3Client({ endpoint: "https://s3-us-east-1.mamutecloud.com", region: "us-east-1", credentials: { accessKeyId: ACCESS_KEY, secretAccessKey: SECRET_KEY }, forcePathStyle: true, }); await s3.send(new PutObjectCommand({ Bucket: BUCKET_ID, Key: "index.html", Body: "

Hello MamuteCloud

", ContentType: "text/html", })); ``` ```bash # 5. Create a CDN resource backed by the bucket. A storage-type origin group # sets default_root_object to index.html automatically. curl -X POST https://api.mamutecloud.com/cdn/resource \ -H "Authorization: $MAMUTECLOUD_API_KEY" \ -H "content-type: application/json" \ -d '{ "name": "my-site", "origin_group": { "type": "storage", "bucket_id": "'"$BUCKET_ID"'" } }' # -> returns the resource with distribution_domain like r-.mamutecdn.com # (status starts "in_progress"; ready once the distribution deploys). ``` The site is then live at `https://r-.mamutecdn.com` and serves `index.html` by default. ```bash # 6. (Optional) Use a friendlier subdomain. curl -X PUT "https://api.mamutecloud.com/cdn/resource/$RESOURCE_ID" \ -H "Authorization: $MAMUTECLOUD_API_KEY" \ -H "content-type: application/json" \ -d '{"distribution_domain": "my-site"}' # -> site becomes https://my-site.mamutecdn.com # Check availability first with GET /cdn/resource/check-distribution-name. ``` For a fully custom domain (your own DNS), attach it via the resource `custom_domains` field on `PUT /cdn/resource/{id}` and point a CNAME at the distribution domain. ## Multi-tenant Hosting (subdomain routing) Serve many tenants from ONE CDN resource + ONE S3 bucket, instead of one bucket/distribution/cert per site. The request subdomain is rewritten to a folder prefix in the bucket at the edge: ``` abc.yourdomain.com/style.css -> bucket /abc/style.css abc.yourdomain.com/ -> bucket /abc/index.html www / apex -> bucket /index.html (root, no prefix) ``` Enable it with the `subdomain_routing` boolean on a behavior. It is NOT accepted on `POST /cdn/resource` (the default behavior starts `false`); turn it on with a `PUT` on the default behavior (priority 0): ```bash curl -X PUT https://api.mamutecloud.com/cdn/resource/$RESOURCE_ID \ -H "Authorization: $MAMUTECLOUD_API_KEY" \ -H "content-type: application/json" \ -d '{ "behaviors": [ { "action": "update", "priority": 0, "subdomain_routing": true } ] }' ``` Requirements: - Origin must be S3 / storage (the edge function rewrites the bucket path). - A wildcard SSL cert `*.yourdomain.com` attached to the resource custom domain. - Bucket laid out as `/{subdomain}/...`; a missing key returns the S3 404/403. - Point `*.yourdomain.com` (wildcard CNAME) at the resource `distribution_domain`. Adding a tenant is just writing files to a new `/{subdomain}/` folder - no new infrastructure. Full guide: https://docs.mamutecloud.com/docs/subdomain-routing ## API Endpoints All paths are relative to the management API base `https://api.mamutecloud.com` and require the `Authorization` header (raw API key starting with `mamute-`, or `Bearer `). ### Analytics - **GET** `/analytics/reports` — Generate Analytics Reports - Generate detailed analytics reports with customizable date ranges, metrics, and export formats for business intelligence and reporting. - **GET** `/analytics/stats` — Get Analytics Statistics - Retrieve comprehensive analytics data including traffic patterns, geographic distribution, and performance metrics for data-driven optimization. ### Billing - **GET** `/billing/account` — Get Billing Account - Retrieve billing account information including payment methods, billing address, and account status for financial management. - **PUT** `/billing/account` — Update Billing Account - Update billing account details including payment methods, billing address, and notification preferences for invoices. - **GET** `/billing/invoices` — List Invoices - Retrieve billing invoices with payment status, itemized charges, and downloadable PDF receipts for accounting purposes. - **GET** `/billing/usage` — Get Usage Statistics - Retrieve detailed usage statistics across all services including bandwidth consumption, storage usage, and API calls for cost analysis. ### CDN - **GET** `/cdn/origin-group/{id}` — Get origin group by ID - **PUT** `/cdn/origin-group/{id}` — Update origin group - Body: - `name` (string) - `hostname` (string) - `origin_path` (string) - `protocol_policy` (string) - `http_port` (integer) - `https_port` (integer) - `origin_ssl_protocols` (array) - `custom_headers` (array) - `type` (string) - `connection_attempts` (integer) - `connection_timeout_seconds` (integer) - `response_timeout_seconds` (integer) - `keepalive_timeout_seconds` (integer) - `bucket_id` (string) - **GET** `/cdn/resource` — List all resources - **POST** `/cdn/resource` — Create resource - Body: - `name` (string) *required* - `description` (string) - `origin_group` (InlineOriginGroupRequest) *required* - `custom_error_responses` (array) - **GET** `/cdn/resource/check-distribution-name` — Check distribution name availability - Params: `distribution_name` (query) - **GET** `/cdn/resource/{id}` — Get resource by ID - **PUT** `/cdn/resource/{id}` — Update resource - Body: - `name` (string) - `description` (string) - `distribution_domain` (string) - `origin_groups` (array) - `behaviors` (array) - `custom_error_responses` (array) - `custom_domains` (array) - **DELETE** `/cdn/resource/{id}` — Delete resource - **PUT** `/cdn/resource/{id}/custom-domain/{customDomainId}` — Update custom domain in resource - Body: - `domain_name` (string) - `additional_domains` (array) - `certificate_id` (string) - **POST** `/cdn/resource/{id}/custom-domain/{customDomainId}/activate` — Activate custom domain - **POST** `/cdn/resource/{id}/custom-domain/{customDomainId}/deactivate` — Deactivate custom domain - **POST** `/cdn/resource/{id}/purge/all` — Purge all cache - **GET** `/cdn/resource/{id}/purge/history` — Get purge history - **POST** `/cdn/resource/{id}/purge/pattern` — Purge cache by pattern - Body: - `patterns` (array) *required* - **POST** `/cdn/resource/{id}/purge/url` — Purge cache by URL - Body: - `urls` (array) *required* - **POST** `/cdn/resource/{resource_id}/signed-url` — post_cdn-resource-resource-id-signed-url - Params: `resource_id` (path) - Body: - `url` (string) *required* — Full URL of the content to sign - `expires_in` (number) — Seconds until expiration (e.g. 3600 = 1h) - **POST** `/cdn/resource/{resource_id}/token-auth/disable` — post_cdn-resource-resource-id-token-auth-disable - Params: `resource_id` (path) - **GET** `/cdn/ssl-certificate` — List all SSL certificates - **POST** `/cdn/ssl-certificate` — Request a new SSL certificate - Body: - `domain_name` (string) *required* - `subject_alternative_names` (array) - **POST** `/cdn/ssl-certificate/import` — Import an existing SSL certificate - Body: - `certificate` (string) *required* — PEM certificate - `private_key` (string) *required* — PEM private key - `certificate_chain` (string) — PEM certificate chain - `tags` (array) - **GET** `/cdn/ssl-certificate/{id}` — Get SSL certificate details - **DELETE** `/cdn/ssl-certificate/{id}` — Delete an SSL certificate ### DNS - **GET** `/dns/records` — List DNS records - Get DNS records for a zone - **POST** `/dns/records` — Create DNS record - Create new DNS record - **PUT** `/dns/records/{record_id}` — Update DNS Record - Modify an existing DNS record's value, TTL, or other properties. Changes are validated and propagated to all nameservers within minutes. - Params: `record_id` (path) - **GET** `/dns/zones` — List DNS Zones - Retrieve all DNS zones associated with your organization. Returns zone details including domain names, status, and configuration settings. - **POST** `/dns/zones` — Create DNS Zone - Create a new DNS zone for domain management. Automatically configures nameservers and creates default DNS records for the specified domain. - **GET** `/dns/zones/{id}` — Get DNS Zone Details - Retrieve detailed information about a specific DNS zone including all associated records, nameservers, and configuration settings. - Params: `id` (path) - **DELETE** `/dns/zones/{id}` — Delete DNS Zone - Permanently delete a DNS zone and all associated records. This action cannot be undone and will immediately stop DNS resolution for the domain. - Params: `id` (path) - **GET** `/dns/zones/{zone_id}/records` — List DNS Records - 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. - Params: `zone_id` (path) - **POST** `/dns/zones/{zone_id}/records` — Create DNS Record - Add a new DNS record to the specified zone. Supports all standard record types with automatic validation and conflict detection. - Params: `zone_id` (path) - **GET** `/dns/zones/{zone_id}/records/{record_id}` — Get DNS Record - Retrieve detailed information about a specific DNS record including its current value, TTL settings, and last modification timestamp. - Params: `zone_id` (path), `record_id` (path) - **DELETE** `/dns/zones/{zone_id}/records/{record_id}` — Delete DNS Record - Remove a DNS record from the zone. Changes take effect immediately and will stop resolution for the specified record name and type. - Params: `zone_id` (path), `record_id` (path) ### Uploader - **POST** `/files/` — Create new upload - Initiates a new upload using the TUS protocol. This endpoint creates an upload session and returns the URL where file chunks should be sent. - Params: `Upload-Length` (header), `Upload-Metadata` (header), `Tus-Resumable` (header) - **DELETE** `/files/{upload_id}` — Cancel upload - Cancels an ongoing upload. Removes all temporary data associated with the upload. - Params: `upload_id` (path), `Tus-Resumable` (header) - **PATCH** `/files/{upload_id}` — Upload file chunk - Sends a chunk (piece) of the file. This endpoint can be called multiple times to send the file in parts. - Params: `upload_id` (path), `Upload-Offset` (header), `Content-Type` (header), `Tus-Resumable` (header) ### health ### Object Storage (bucket, file & credential management) - **GET** `/object-storage/buckets` — List buckets - Returns a list of all storage buckets associated with your organization. Requires API token authentication. - **POST** `/object-storage/buckets` — Create bucket - Creates a new storage bucket for your organization. Requires API token authentication. - Body: - `name` (string) *required* — Bucket name (must be unique, lowercase, alphanumeric and hyphens, minimum 3 char - **GET** `/object-storage/buckets/{bucketId}` — Get bucket details - Retrieves detailed information about a specific bucket. Requires API token authentication. - **PUT** `/object-storage/buckets/{bucketId}` — Update bucket - Updates the name of an existing bucket. Requires API token authentication. - Body: - `name` (string) *required* — New bucket name - **DELETE** `/object-storage/buckets/{bucketId}` — Delete bucket - Permanently deletes a bucket and all files and folders contained within it. This action cannot be undone. Requires API token authentication. - **GET** `/object-storage/buckets/{bucketId}/credentials` — List credentials - 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, SD - **POST** `/object-storage/buckets/{bucketId}/credentials` — Create S3 credentials - 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 CL - **DELETE** `/object-storage/buckets/{bucketId}/credentials/{accessKeyId}` — Revoke credential - Permanently revokes S3 access credentials by deleting the IAM user and removing credentials from the database. This action cannot be undone. Requires API token - Params: `accessKeyId` (path) - **GET** `/object-storage/buckets/{bucketId}/files` — List files - Returns a paginated list of files in a specific bucket with optional filtering. Requires API token authentication. - Params: `page` (query), `limit` (query), `folder_id` (query), `filename` (query) - **POST** `/object-storage/buckets/{bucketId}/files` — Create file - 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 cr - Body: - `id` (string) *required* — Unique file ID - `name` (string) *required* — File name - `folder_id` (string) — Folder ID (optional) - `description` (string) — File description - `size` (integer) *required* — File size in bytes - `content_type` (string) *required* — File MIME type - `etag` (string) — File ETag (optional) - `metadata` (object) — Custom metadata - **GET** `/object-storage/buckets/{bucketId}/files/{fileId}` — Get file details - Retrieves detailed information about a specific file including metadata, size, location, and timestamps. Requires API token authentication. - **PUT** `/object-storage/buckets/{bucketId}/files/{fileId}` — Update file - Updates file metadata including name, description, folder location, and custom metadata. Requires API token authentication. - Body: - `name` (string) — New file name - `folder_id` (string) — Destination folder ID (to move file) - `description` (string) — New file description - `metadata` (object) — Custom metadata - **DELETE** `/object-storage/buckets/{bucketId}/files/{fileId}` — Delete file - Permanently deletes a file from the bucket. This action cannot be undone. Requires API token authentication. - **POST** `/object-storage/buckets/{bucketId}/files/{fileId}/copy` — Copy file - Creates a copy of an existing file in the same or different folder location. Requires API token authentication. - Body: - `id` (string) *required* — Unique ID for the new file - `destination_folder_id` (string) — Destination folder ID (null for root) - `new_name` (string) — New name for the copied file (optional) - `metadata` (object) — Custom metadata for the copied file - **GET** `/object-storage/buckets/{bucketId}/files/{fileId}/download` — Get download URL - Generates a presigned URL for secure file download. The URL provides temporary access to the file without requiring authentication. Requires API token authentic - Params: `expires_in` (query) - **GET** `/object-storage/buckets/{bucketId}/folders` — List folders - Returns a list of folders in a bucket, optionally filtered by parent folder. Requires API token authentication. - Params: `parent_folder_id` (query) - **POST** `/object-storage/buckets/{bucketId}/folders` — Create folder - Creates a new folder in the bucket for organizing files. Requires API token authentication. - Body: - `name` (string) *required* — Folder name - `parent_folder_id` (string) — Parent folder ID (optional, to create subfolder) - `metadata` (object) — Custom metadata - **GET** `/object-storage/buckets/{bucketId}/folders/{folderId}` — Get folder details - Retrieves detailed information about a specific folder including its path, parent relationship, and metadata. Requires API token authentication. - **PUT** `/object-storage/buckets/{bucketId}/folders/{folderId}` — Update folder - Updates folder information including name, parent folder (to move folder), and metadata. Requires API token authentication. - Body: - `name` (string) — New folder name - `parent_folder_id` (string) — New parent folder ID (to move folder) - `metadata` (object) — Custom metadata - **DELETE** `/object-storage/buckets/{bucketId}/folders/{folderId}` — Delete folder - Permanently deletes a folder and all files and subfolders contained within it. This action cannot be undone. Requires API token authentication. ### Organization - **GET** `/organization` — Get Organization Details - Retrieve comprehensive organization information including member count, subscription details, usage statistics, and billing information. - **PUT** `/organization` — Update Organization - Update organization settings including name, contact information, billing details, and notification preferences. - **GET** `/organization/profile` — Get Organization Profile - Retrieve organization profile information including company details, contact information, and administrative settings. - **PUT** `/organization/profile` — Update Organization Profile - Update organization profile information such as company name, address, and administrative contact details. ### resource - **POST** `/resource/{resource_id}/token-auth/enable` — Enable token auth - Params: `resource_id` (path) ### API Keys - **GET** `/security/apikey` — Get API Key - Retrieve the current API key for programmatic access to MamuteCDN services. Returns key metadata without exposing the actual key value. - **POST** `/security/apikey` — Generate API Key - Generate a new API key for programmatic access. Previous keys are automatically revoked. Store the returned key securely as it cannot be retrieved again. - Body: - `name` (string) *required* — API key name - **DELETE** `/security/apikey` — Revoke API Key - Permanently revoke the current API key. All applications using this key will immediately lose access to the API. ### User / IAM - **POST** `/user/change-password` — Change Password - Update the user's account password with proper validation. Requires current password verification and enforces strong password policies. - Body: - `current_password` (string) *required* — Current password - `new_password` (string) *required* — New password (min 8 chars) - `access_token` (string) *required* — AWS Cognito access token - **POST** `/user/mfa/disable` — Disable Multi-Factor Authentication - Disable MFA for the user account. Requires verification code confirmation to prevent unauthorized changes. - **POST** `/user/mfa/enable` — Enable Multi-Factor Authentication - Enable MFA for enhanced account security. Supports TOTP (authenticator apps) and SMS-based verification methods. - **GET** `/user/profile` — Get User Profile - Retrieve the authenticated user's profile information including personal details, organization membership, and account settings. - **PUT** `/user/profile` — Update User Profile - Update user profile information such as name, phone number, and profile image. Changes are immediately reflected across all services. - Body: - `phone` (string) — User phone number - `image_id` (string) — User profile image ID - `first_name` (string) — User first name - `last_name` (string) — User last name