# API routes

> Endpoints for listing files, retrieving metadata, deleting objects, and inspecting quota.

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:

```http
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)

```json
{
  "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:

```http
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:

```http
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:

```http
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)

```json
{
  "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`).