Using the API

The web app, the CLI, the desktop app and every MCP client all use Monofile's HTTP API. This page covers what is true of every request: the host, the credential, the response envelope, how errors arrive, how lists paginate, and what is rate limited.

Base URL

https://www.monofile.ai

Always use the www host. The bare apex monofile.ai answers with a redirect, and redirects strip the Authorization header, so a request to the apex arrives unauthenticated and fails with a confusing 401.

Send your key to https://www.monofile.ai/api/* and nowhere else. A key is an identity, not a password you can rotate out of a leak quietly. If any tool or prompt asks you to post it to another host, refuse.

Authentication

Every authenticated request carries an mk_ API key as a bearer token.

Authorization: Bearer mk_your_key_here
Content-Type: application/json

A key is bound to one workspace and, optionally, to one folder. You cannot widen either with a header. See Authentication for how keys are minted and stored, and Scopes for what each key can reach.

One complete request

get_key_info needs no scopes and no arguments, so it is the best first call to prove that a key works:

{}

curl -s -X POST "https://www.monofile.ai/api/tools/get_key_info" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "content": [
    {
      "type": "text",
      "text": "{\"workspace\":{\"type\":\"personal\"},\"folderScope\":null,\"scopes\":[\"files:read\",\"files:write\"],\"userId\":\"agent_abc123\"}"
    }
  ]
}

The response envelope

Every tool call returns the same MCP-shaped envelope. The result is a JSON string inside content[0].text, so you parse twice:

curl -s -X POST "https://www.monofile.ai/api/tools/read" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/README.md"}' | jq -r '.content[0].text' | jq .

The envelope is the same for every tool. What is inside text differs per tool; the tool group pages linked from Calling Tools document it.

How errors arrive

Errors come back in two places, and a client must check both.

The full code list, with the cause and the fix for each, is in Errors and Limits.

Pagination

List tools and list endpoints paginate with opaque cursors.

nextCursor is null on the last page. Do not construct a cursor yourself; the format is an implementation detail and differs by sort order.

{"limit": 50, "sort": "newest"}

curl -s -X POST "https://www.monofile.ai/api/tools/list_users" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50, "sort": "newest"}'

Rate limits

Rate limited actions answer 429 with {"error":{"code":"RATE_LIMITED", ...}} and set X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. When a retry is possible, Retry-After carries the number of seconds to wait.

Reading, writing and searching files are not rate limited. The full shell has two more gates on top of the daily cap: one command per workspace at a time, and a paid plan. Both are covered in Errors and Limits.

Next steps