API reference
Where to find the mountable.io OpenAPI document, how to authenticate with an API key, and which endpoints manage filesystems and files.
The management JSON API lives under /api/v1/; sign-in and device/token
routes also use /auth/. The OpenAPI document is served at
/api/v1/openapi.json; generate a client from it
with an OpenAPI tool and configure its credentials as described below. The
files API (/api/v1/filesystems/{fs_id}/files, /list
and /changes) authenticates with session tokens and is described on its own
page, not in the OpenAPI document.
Authentication
| Caller | Send |
|---|---|
| Your backend | Authorization: Bearer mtbl_… (an API key) |
| Your provisioning service | Authorization: Bearer mtblm_… (a management key) |
| The console | the session cookie (set by sign-in) |
| The CLI | its access token from mountable login |
What each key may do is listed under Permissions.
Grants, API keys and deleting a filesystem take a person or a management key
(an API key receives 403 management_key_required); mount sessions and
webhooks take a person or an API key (a management key receives
403 api_key_required). Keys cannot administer organisations, members,
groups, invitations, management keys or billing: a valid key on a
people-only route receives 403 api_key_forbidden; a revoked/expired key
receives 401 unauthenticated.
Management request bodies use JSON. Cookie-authenticated writes also require
the public origin in Origin; browsers send their protected session cookie
automatically. Do not reuse a browser cookie as an MCP credential.
The device/token routes use OAuth form encoding and OAuth error responses;
normally use CLI login rather than implementing
that exchange yourself.
Most used routes
| Method and path | Does |
|---|---|
POST /api/v1/mount-sessions | create a mount session; returns a one-time ticket, or a session token with "credential": "token" |
DELETE /api/v1/mount-sessions/{session_id} | revoke a session |
GET /api/v1/me | who is calling; for a key, its api_key: {id, org_id} or management_key: {id, org_id} |
GET /api/v1/orgs/{org_id}/filesystems | list filesystems (an API key sees those it has a grant on) |
POST /api/v1/orgs/{org_id}/filesystems | create a filesystem, optionally with limits per end user (management key) |
PATCH /api/v1/orgs/{org_id}/filesystems/{fs_id} | change a filesystem's limits: spend cap, operation rate, quotas (management key) |
PUT /api/v1/orgs/{org_id}/filesystems/{fs_id}/grants | set a grant (management key) |
POST /api/v1/orgs/{org_id}/filesystems/{fs_id}/webhooks | call your HTTPS endpoint when files change (webhooks) |
Every operation in every client
Each operation a key can perform has a CLI command and a method in both
SDKs. Creating, changing and deleting filesystems, keys and grants take a
management key; tickets, sessions,
files and webhooks take an API key. The CLI and the SDKs find the
organisation themselves; over HTTP it is api_key.org_id (or
management_key.org_id) from GET /api/v1/me. Paths below are under
/api/v1/orgs/{org_id} unless they start with /api/v1/.
| HTTP | CLI | Python | TypeScript |
|---|---|---|---|
GET /api/v1/me | mountable orgs list | (automatic) | (automatic) |
GET /filesystems | mountable fs list | list_filesystems() | listFilesystems() |
POST /filesystems | mountable fs create NAME [limits] | create_filesystem(name, …) | createFilesystem(name, { … }) |
GET /filesystems/{fs_id} | mountable fs get FS_ID | get_filesystem(fs_id) | getFilesystem(fsId) |
PATCH /filesystems/{fs_id} | mountable fs update FS_ID [limits] | update_filesystem(fs_id, …) | updateFilesystem(fsId, { … }) |
GET /filesystems/{fs_id}/usage | mountable fs usage FS_ID | filesystem_usage(fs_id) | filesystemUsage(fsId) |
DELETE /filesystems/{fs_id} | mountable fs delete FS_ID | delete_filesystem(fs_id) | deleteFilesystem(fsId) |
POST /api-keys, GET /api-keys, DELETE /api-keys/{key_id} | mountable api-keys create, list, revoke | create_api_key, list_api_keys, revoke_api_key | createApiKey, listApiKeys, revokeApiKey |
POST, GET /filesystems/{fs_id}/s3-keys, DELETE …/s3-keys/{access_key_id} | mountable s3-keys create, list, revoke | create_s3_key, list_s3_keys, revoke_s3_key | createS3Key, listS3Keys, revokeS3Key |
GET, PUT /filesystems/{fs_id}/grants, DELETE …/grants/{grant_id} | mountable grants list, set, delete | list_grants, set_grant, delete_grant | listGrants, setGrant, deleteGrant |
POST /api/v1/mount-sessions (ticket) | mountable ticket create FS_ID | create_mount_ticket(fs_id, …) | createMountTicket(fsId, { … }) |
POST /api/v1/mount-sessions (token) | used by the CLI's files commands | used by filesystem() | used by filesystem() |
GET /filesystems/{fs_id}/mount-sessions | mountable sessions list FS_ID | list_mount_sessions(fs_id) | listMountSessions(fsId) |
DELETE /api/v1/mount-sessions/{session_id} | mountable sessions revoke SESSION_ID | revoke_mount_session(session_id) | revokeMountSession(sessionId) |
POST /filesystems/{fs_id}/webhooks | mountable webhooks create FS_ID URL | create_webhook(fs_id, url) | createWebhook(fsId, url) |
GET /filesystems/{fs_id}/webhooks | mountable webhooks list FS_ID | list_webhooks(fs_id) | listWebhooks(fsId) |
POST …/webhooks/{webhook_id}:rotate-secret | mountable webhooks rotate-secret FS_ID WEBHOOK_ID | rotate_webhook_secret(…) | rotateWebhookSecret(…) |
POST …/webhooks/{webhook_id}:enable | mountable webhooks enable FS_ID WEBHOOK_ID | enable_webhook(…) | enableWebhook(…) |
DELETE …/webhooks/{webhook_id} | mountable webhooks delete FS_ID WEBHOOK_ID | delete_webhook(…) | deleteWebhook(…) |
GET /api/v1/filesystems/{fs_id}/files/{path} | mountable files read FS_ID PATH | fs.read(path) | fs.read(path) |
PUT /api/v1/filesystems/{fs_id}/files/{path} | mountable files write FS_ID PATH | fs.write(path, data) | fs.write(path, data) |
DELETE /api/v1/filesystems/{fs_id}/files/{path} | mountable files delete FS_ID PATH | fs.delete(path) | fs.delete(path) |
GET /api/v1/filesystems/{fs_id}/list/{path} | mountable files list FS_ID [PATH] | fs.list(path) | fs.list(path) |
GET /api/v1/filesystems/{fs_id}/changes | mountable files changes FS_ID | fs.changes() | fs.changes() |
Python and TypeScript methods are on the client (client.…) except the file
operations, which are on a filesystem handle (fs = client.filesystem(…)).
Mounting is a process, so only the CLI mounts. Members, groups,
invitations, management keys and billing need a person in the console.
Session tokens
A session created with "credential": "token" returns
token: "mtblst_…" instead of a ticket: shown once, active at once, with
ticket and ticket_expires_at null. It is the bearer credential of the
files API, which reads and writes files over HTTPS without
mounting. Create token sessions with an API key or a CLI login
(a console cookie gets 403 token_needs_key_or_cli). Grants, mode, billing
and expiry apply exactly as for tickets.
A token is never exchanged or renewed (:exchange and :renew answer
409 token_session); create a new session instead. A replay with the same
idempotency_key returns the session with token: null. Session lists show
credential: "token", and revoking the session, or any change that revokes
mounts, ends the token too.
Errors
Expected management-operation errors carry a code, for example
{"detail": {"code": "no_grant"}}. Validation errors return 422 with a
list of field problems. Check status and payload; unmatched routes, proxies
or unexpected server failures need not have that same structure.
| Status / code | Recovery |
|---|---|
401 unauthenticated | Sign in again or replace the expired/revoked key. |
402 payment_required | Give the returned billing URL to an owner/admin; do not retry mounting until the prerequisite is resolved. |
403 | Check the caller's role, filesystem grant and requested mode; a key cannot use people-only operations. |
404 | Check the ID and selected organisation; a key cannot discover another organisation's resources. |
409 | Read the specific code and current state, such as last-owner protection or a concurrent request. |
429 | Wait the indicated retry interval. |
503 | A service or sign-in/billing method is unavailable; follow the page's recovery action or contact support. For an uncertain write, inspect the outcome before retrying. |
For ambiguous writes and one-time tickets, follow the retry rules rather than blindly repeating creation.