mountable.io

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

CallerSend
Your backendAuthorization: Bearer mtbl_… (an API key)
Your provisioning serviceAuthorization: Bearer mtblm_… (a management key)
The consolethe session cookie (set by sign-in)
The CLIits 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 pathDoes
POST /api/v1/mount-sessionscreate 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/mewho is calling; for a key, its api_key: {id, org_id} or management_key: {id, org_id}
GET /api/v1/orgs/{org_id}/filesystemslist filesystems (an API key sees those it has a grant on)
POST /api/v1/orgs/{org_id}/filesystemscreate 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}/grantsset a grant (management key)
POST /api/v1/orgs/{org_id}/filesystems/{fs_id}/webhookscall 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/.

HTTPCLIPythonTypeScript
GET /api/v1/memountable orgs list(automatic)(automatic)
GET /filesystemsmountable fs listlist_filesystems()listFilesystems()
POST /filesystemsmountable fs create NAME [limits]create_filesystem(name, …)createFilesystem(name, { … })
GET /filesystems/{fs_id}mountable fs get FS_IDget_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}/usagemountable fs usage FS_IDfilesystem_usage(fs_id)filesystemUsage(fsId)
DELETE /filesystems/{fs_id}mountable fs delete FS_IDdelete_filesystem(fs_id)deleteFilesystem(fsId)
POST /api-keys, GET /api-keys, DELETE /api-keys/{key_id}mountable api-keys create, list, revokecreate_api_key, list_api_keys, revoke_api_keycreateApiKey, listApiKeys, revokeApiKey
POST, GET /filesystems/{fs_id}/s3-keys, DELETE …/s3-keys/{access_key_id}mountable s3-keys create, list, revokecreate_s3_key, list_s3_keys, revoke_s3_keycreateS3Key, listS3Keys, revokeS3Key
GET, PUT /filesystems/{fs_id}/grants, DELETE …/grants/{grant_id}mountable grants list, set, deletelist_grants, set_grant, delete_grantlistGrants, setGrant, deleteGrant
POST /api/v1/mount-sessions (ticket)mountable ticket create FS_IDcreate_mount_ticket(fs_id, …)createMountTicket(fsId, { … })
POST /api/v1/mount-sessions (token)used by the CLI's files commandsused by filesystem()used by filesystem()
GET /filesystems/{fs_id}/mount-sessionsmountable sessions list FS_IDlist_mount_sessions(fs_id)listMountSessions(fsId)
DELETE /api/v1/mount-sessions/{session_id}mountable sessions revoke SESSION_IDrevoke_mount_session(session_id)revokeMountSession(sessionId)
POST /filesystems/{fs_id}/webhooksmountable webhooks create FS_ID URLcreate_webhook(fs_id, url)createWebhook(fsId, url)
GET /filesystems/{fs_id}/webhooksmountable webhooks list FS_IDlist_webhooks(fs_id)listWebhooks(fsId)
POST …/webhooks/{webhook_id}:rotate-secretmountable webhooks rotate-secret FS_ID WEBHOOK_IDrotate_webhook_secret(…)rotateWebhookSecret(…)
POST …/webhooks/{webhook_id}:enablemountable webhooks enable FS_ID WEBHOOK_IDenable_webhook(…)enableWebhook(…)
DELETE …/webhooks/{webhook_id}mountable webhooks delete FS_ID WEBHOOK_IDdelete_webhook(…)deleteWebhook(…)
GET /api/v1/filesystems/{fs_id}/files/{path}mountable files read FS_ID PATHfs.read(path)fs.read(path)
PUT /api/v1/filesystems/{fs_id}/files/{path}mountable files write FS_ID PATHfs.write(path, data)fs.write(path, data)
DELETE /api/v1/filesystems/{fs_id}/files/{path}mountable files delete FS_ID PATHfs.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}/changesmountable files changes FS_IDfs.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 / codeRecovery
401 unauthenticatedSign in again or replace the expired/revoked key.
402 payment_requiredGive the returned billing URL to an owner/admin; do not retry mounting until the prerequisite is resolved.
403Check the caller's role, filesystem grant and requested mode; a key cannot use people-only operations.
404Check the ID and selected organisation; a key cannot discover another organisation's resources.
409Read the specific code and current state, such as last-owner protection or a concurrent request.
429Wait the indicated retry interval.
503A 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.