# Files

List, read, write, and delete files by path; inspect and restore revisions by stable file ID.

| Method | Operation | Path |
| --- | --- | --- |
| **`GET`** | [List files](#list-files) | `/v0/buckets/:bucketId/objects` |
| **`GET`** | [Read a file](#read-a-file) | `/v0/buckets/:bucketId/objects/*` |
| **`HEAD`** | [Inspect a file](#inspect-a-file) | `/v0/buckets/:bucketId/objects/*` |
| **`PUT`** | [Write a file](#write-a-file) | `/v0/buckets/:bucketId/objects/*` |
| **`DELETE`** | [Delete a file](#delete-a-file) | `/v0/buckets/:bucketId/objects/*` |
| **`GET`** | [List file versions](#list-file-versions) | `/v0/files/:fileId/versions` |
| **`GET`** | [Read a file version](#read-a-file-version) | `/v0/files/:fileId/versions/:versionId/content` |
| **`POST`** | [Restore a file version](#restore-a-file-version) | `/v0/files/:fileId/restore` |

## List files

List file metadata in a bucket.

**`GET`** `/v0/buckets/:bucketId/objects`

- **API key permission:** Read-only or Read/write

### Parameters

- `bucketId` — bucket UUID.
- `path` — optional exact normalized path.
- `prefix` — optional normalized path prefix.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/buckets/<bucket-id>/objects" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "files": [{
    "id": "<file-id>",
    "bucketId": "<bucket-id>",
    "path": "web/index.html",
    "contentType": "text/html; charset=utf-8",
    "bytes": 1480,
    "currentVersionId": "<version-id>"
  }],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

### Related interfaces

- **CLI:** `interfold files ls --bucket <bucket-id>`
- **MCP:** `list_files`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Read a file

Stream raw file content by normalized path.

**`GET`** `/v0/buckets/:bucketId/objects/*`

- **API key permission:** Read-only or Read/write

### Parameters

- `bucketId` — bucket UUID.
- `*` — file path, such as `web/index.html`.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/buckets/<bucket-id>/objects/<path>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~text
<raw file bytes>
~~~

### Behavior and errors

- The response uses the stored `Content-Type` and `Content-Length`.
- Authenticated object reads use `Cache-Control: private, no-store`.

### Related interfaces

- **CLI:** `interfold files cat /web/index.html --bucket <bucket-id>`
- **MCP:** `read_file (text files up to 256 KiB)`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Inspect a file

Read object headers without downloading its body.

**`HEAD`** `/v0/buckets/:bucketId/objects/*`

- **API key permission:** Read-only or Read/write

### Parameters

- `bucketId` — bucket UUID.
- `*` — file path.

### Request

~~~sh
curl -X HEAD \
  "https://api.interfold.dev/v0/buckets/<bucket-id>/objects/<path>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~http
Content-Type: text/html; charset=utf-8
Content-Length: 1480
Interfold-File-Id: <file-id>
~~~

### Behavior and errors

- The response also includes `Interfold-Version-Id` when a current revision exists.

### Related interfaces

- **CLI:** `interfold files stat /web/index.html --bucket <bucket-id>`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Write a file

Create or replace a file using the request body as raw bytes.

**`PUT`** `/v0/buckets/:bucketId/objects/*`

- **API key permission:** Read/write

### Parameters

- `bucketId` — bucket UUID.
- `*` — destination file path.
- `Content-Type` — stored with the file; defaults to `application/octet-stream`.
- `If-Match` — optional current version UUID; stale writes return 409.

### Request

~~~sh
curl -X PUT \
  "https://api.interfold.dev/v0/buckets/<bucket-id>/objects/<path>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: text/html; charset=utf-8" \
  --data-binary @<local-file>
~~~

### Response

~~~json
{
  "id": "<file-id>",
  "bucketId": "<bucket-id>",
  "path": "web/index.html",
  "contentType": "text/html; charset=utf-8",
  "bytes": 1480,
  "fileId": "<file-id>",
  "versionId": "<new-version-id>",
  "deployment": {
    "siteId": "<site-id>",
    "sourcePath": "web/index.html",
    "status": "READY"
  }
}
~~~

### Behavior and errors

- Writes accept no query parameters.
- Every write creates a new immutable revision. The file ID stays stable across overwrites and renames.
- An attached site serves static file changes immediately.
- Writing `/api/*.ts` or `/cron/*.ts` also deploys the runtime source. Inspect the optional `deployment.status`; saving the file does not prove the runtime is ready.

### Related interfaces

- **CLI:** `interfold files put ./index.html /web/index.html --bucket <bucket-id>`
- **MCP:** `write_file (text files)`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Delete a file

Delete a file and reconcile any attached runtime source.

**`DELETE`** `/v0/buckets/:bucketId/objects/*`

- **API key permission:** Read/write

### Parameters

- `bucketId` — bucket UUID.
- `*` — file path.

### Request

~~~sh
curl -X DELETE \
  "https://api.interfold.dev/v0/buckets/<bucket-id>/objects/<path>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "id": "<file-id>",
  "bucketId": "<bucket-id>",
  "path": "web/old.html"
}
~~~

### Behavior and errors

- Deleting function or cron source also removes or pauses its deployed runtime.

### Related interfaces

- **CLI:** `interfold files rm /web/old.html --bucket <bucket-id>`
- **MCP:** `delete_file`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## List file versions

List retained revisions newest first.

**`GET`** `/v0/files/:fileId/versions`

- **API key permission:** Read-only or Read/write

### Parameters

- `fileId` — stable file UUID.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/files/:fileId/versions" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{ "fileId": "<file-id>", "currentVersionId": "<version-id>", "versions": [{ "id": "<version-id>", "bytes": 1480, "contentType": "text/html", "createdAt": "<timestamp>", "restoredFromVersionId": null }], "pagination": { "hasMore": false, "nextOffset": null } }
~~~

### Related interfaces

- **CLI:** `interfold files history ls <file-id>`
- **MCP:** `list_file_versions`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Read a file version

Stream exact historical bytes for a retained revision.

**`GET`** `/v0/files/:fileId/versions/:versionId/content`

- **API key permission:** Read-only or Read/write

### Parameters

- `fileId` — stable file UUID.
- `versionId` — revision UUID.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/files/:fileId/versions/:versionId/content" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~text
<raw file bytes>
~~~

### Behavior and errors

- For binary or large revisions, use `interfold files history get <file-id> <version-id> <local-file>`.

### Related interfaces

- **CLI:** `interfold files history cat <file-id> <version-id>`
- **MCP:** `read_file_version (text files up to 256 KiB)`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Restore a file version

Copy historical content into a new current revision.

**`POST`** `/v0/files/:fileId/restore`

- **API key permission:** Read/write

### Parameters

- `fileId` — stable file UUID.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/files/:fileId/restore" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @<local-file>
~~~

### Response

~~~json
{ "fileId": "<file-id>", "versionId": "<new-version-id>", "restoredFromVersionId": "<old-version-id>", "path": "web/index.html" }
~~~

### Behavior and errors

- A stale current version returns 409. Restore preserves the current path and access rules and reconciles function or cron source.

### Related interfaces

- **CLI:** `interfold files history restore <file-id> <old-version-id> <current-version-id>`
- **MCP:** `restore_file_version`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

## Shared behavior

All operations use the [API authentication](/api-reference/authentication),
[error](/api-reference/errors), and [rate-limit](/api-reference/rate-limits)
contracts. List operations use [standard pagination](/api-reference/pagination)
unless the operation says otherwise.