> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# Files

> Upload documents for endpoints that take files, and download files that endpoints return.

Some endpoints upload a file to the site, such as a receipt, a résumé or an invoice, and some return one, such as a statement PDF. Peel keeps those files encrypted, owned by your account, for one hour.

## Limits

| | Limit |
| - | - |
| One file | 25 MiB through an upload URL, 5 MB as base64 |
| One call | 20 files and 50 MiB in total |
| Active files per account | 20 |
| Lifetime | 1 hour, then deleted |

## Upload a file

Ask for a one-time upload URL, then `PUT` the raw bytes to it. The URL works once and expires after 15 minutes. It needs no API key, so keep it private.

```bash theme={null}
curl https://api.peel.sh/v1/files/uploads \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "invoice.pdf", "mime_type": "application/pdf"}'
```

```json theme={null}
{
  "upload_url": "https://api.peel.sh/public/uploads/…",
  "method": "PUT",
  "expires_at": "2026-11-04T07:15:00.000Z",
  "max_bytes": 26214400
}
```

```bash theme={null}
curl -T invoice.pdf "$UPLOAD_URL"
```

The `PUT` returns the file's metadata. Pass its `file_id` as the endpoint's file input.

```json theme={null}
{
  "file_id": "4f3c2a1e-9b8d-4c7a-8e6f-5d4c3b2a1f0e",
  "name": "invoice.pdf",
  "mime_type": "application/pdf",
  "size": 1843202,
  "expires_at": "2026-11-04T08:00:00.000Z"
}
```

For small files you can instead send base64 in one request: `POST /v1/files` with `name`, `mime_type` and `data_base64`.

## Download a file

An endpoint that saves a file returns its metadata (`file_id`, `name`, `mime_type`, `size`, `sha256`). Download the bytes with:

```bash theme={null}
curl -o statement.pdf https://api.peel.sh/v1/files/$FILE_ID/content -H "X-API-Key: $PEEL_API_KEY"
```

`GET /v1/files/{file_id}` returns the same file as base64 JSON when it is 5 MB or smaller. `DELETE /v1/files/{file_id}` removes it before it expires.

## From an agent

The MCP server has the same tools. Agents should use `create_file_upload` and then `curl -T`, so the file never passes through the conversation. `upload_file` and `get_file` take and return base64 and are meant for small files.

## Related pages

* [MCP server](https://docs.peel.sh/features/mcp-server.md)
* [Errors](https://docs.peel.sh/reference/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.