Docs menu
Docs/Developer interfaces/REST API/Files
View as Markdown

Files

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

Method Operation Path
GET List files /v0/buckets/:bucketId/objects
GET Read a file /v0/buckets/:bucketId/objects/*
HEAD Inspect a file /v0/buckets/:bucketId/objects/*
PUT Write a file /v0/buckets/:bucketId/objects/*
DELETE Delete a file /v0/buckets/:bucketId/objects/*
GET List file versions /v0/files/:fileId/versions
GET Read a file version /v0/files/:fileId/versions/:versionId/content
POST 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

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

Response

{
  "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 }
}
  • CLI: interfold files ls --bucket <bucket-id>
  • MCP: list_files

See Errors for the standard error envelope and 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

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

Response

<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.
  • CLI: interfold files cat /web/index.html --bucket <bucket-id>
  • MCP: read_file (text files up to 256 KiB)

See Errors for the standard error envelope and 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

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

Response

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.
  • CLI: interfold files stat /web/index.html --bucket <bucket-id>

See Errors for the standard error envelope and 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

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

{
  "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.
  • CLI: interfold files put ./index.html /web/index.html --bucket <bucket-id>
  • MCP: write_file (text files)

See Errors for the standard error envelope and 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

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

Response

{
  "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.
  • CLI: interfold files rm /web/old.html --bucket <bucket-id>
  • MCP: delete_file

See Errors for the standard error envelope and 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

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

Response

{ "fileId": "<file-id>", "currentVersionId": "<version-id>", "versions": [{ "id": "<version-id>", "bytes": 1480, "contentType": "text/html", "createdAt": "<timestamp>", "restoredFromVersionId": null }], "pagination": { "hasMore": false, "nextOffset": null } }
  • CLI: interfold files history ls <file-id>
  • MCP: list_file_versions

See Errors for the standard error envelope and 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

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

Response

<raw file bytes>

Behavior and errors

  • For binary or large revisions, use interfold files history get <file-id> <version-id> <local-file>.
  • CLI: interfold files history cat <file-id> <version-id>
  • MCP: read_file_version (text files up to 256 KiB)

See Errors for the standard error envelope and 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

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

{ "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.
  • CLI: interfold files history restore <file-id> <old-version-id> <current-version-id>
  • MCP: restore_file_version

See Errors for the standard error envelope and Authentication for API key handling.

Shared behavior

All operations use the API authentication, error, and rate-limit contracts. List operations use standard pagination unless the operation says otherwise.

On this page