API routes

This section documents the REST API endpoints for managing files and checking quota capacity.

List files (GET /files)

Retrieves the authenticated account file listing, ordered by creation timestamp descending:

GET /files HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>

Required scope: files:read.

Query parameters

Parameter	Type	Description
limit	integer	Number of items to return from 1 to 200. Default is 50.
cursor	string	Opaque pagination cursor string to fetch the subsequent page.
search	string	Case-insensitive substring match against file names. Up to 256 characters.
kind	string	File extension or type filter. Up to 64 characters.
is_media	string	Filter for media objects (true or false).

Response example (200 OK)

{
  "items": [
    {
      "id": "file_01h8abc123def456",
      "name": "annual-report.pdf",
      "kind": "pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "size_bytes": 1048576,
      "status": "ready",
      "created_at": "2026-10-15T12:00:00Z",
      "updated_at": "2026-10-15T12:00:05Z",
      "deleted_at": null,
      "is_media": false,
      "taken_at": null,
      "agent_sync_enabled": false
    }
  ],
  "next_cursor": "eyJhbGciOiJIUzI1NiJ9..."
}

File metadata (GET /files/{file_id})

Retrieves metadata and processing state for a specific file:

GET /files/file_01h8abc123def456 HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>

Required scope: files:read.

Possible status values:

• uploaded: binary payload accepted by the storage ingress.
• processing: background validation and chunk assembly in progress.
• ready: file is fully assembled and available for download.
• failed: an error occurred during ingestion or verification.

Delete file (DELETE /files/{file_id})

Performs soft deletion of a file:

DELETE /files/file_01h8abc123def456 HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>

Required scope: files:delete.

Soft deletion immediately frees storage space in your quota. Calling delete repeatedly on an already-deleted item is safe and idempotent.

Inspect quota (GET /quota)

Returns storage utilization metrics for the active tenant:

GET /quota HTTP/1.1
Host: api.mmwcloud.tech
Authorization: Bearer mmwc_<prefix>_<secret>

Required scope: quota:read or files:read.

Response example (200 OK)

{
  "used_bytes": 107374182400,
  "reserved_bytes": 0,
  "total_quota_bytes": 1099511627776,
  "free_bytes": 992137445376,
  "unlimited": false,
  "is_read_only": false
}

Response fields:

• used_bytes: bytes currently occupied by confirmed files.
• reserved_bytes: byte capacity held by ongoing uploads.
• total_quota_bytes: total capacity ceiling granted by the subscription plan.
• free_bytes: remaining unallocated capacity in bytes.
• unlimited: flag indicating whether the plan has no quota cap (true or false).
• is_read_only: flag set when plan lapses and write actions are restricted (true or false).