# Quickerfile

> Two things you can do with a receipt, an invoice or a bill. Post the document
> to /api/v1/receipts and get the vendor, date, totals, tax and line items back,
> plus the same document renamed YYYY-MM-DD_Vendor_Amount.pdf with that data
> written into its searchable document metadata. Or post it to /api/v1/redact
> and get it back with the personal data blacked out and no text left underneath
> the bars.

## 1. Get a key

Create one at https://www.quickerfile.com/dashboard/api-keys. It is shown once and stored only
as a hash. Send it as `Authorization: Bearer qf_live_...` on every request.

## 2. Connect a client

Remote MCP endpoint (Streamable HTTP, stateless, bearer authenticated):

    https://www.quickerfile.com/api/mcp

Verification status, stated once for all of it: no client below has been run
against the live endpoint yet. Each snippet's shape is read off that vendor's
own documentation, and the two CLI commands have been run far enough to inspect
the config they write. Treat the shapes as documented, not as proven.

Claude Code — command form checked against `claude mcp add --help`:

    claude mcp add --transport http --scope user quickerfile https://www.quickerfile.com/api/mcp \
      --header "Authorization: Bearer qf_live_..."

`--scope user` matters: the CLI defaults to `local`, which is the current
project only. `user` writes it to your user config on this machine.

claude.ai and Claude Desktop — Settings, Connectors, Add custom connector. Paste
https://www.quickerfile.com/api/mcp and give the API key as the bearer token. A Desktop build with
no custom-connector option reaches the same endpoint through the mcp-remote
bridge in `claude_desktop_config.json`; put the header value in `env`, because
several clients do not escape spaces inside `args`.

The field name is the whole difference between the JSON clients — `url`,
`serverUrl` and `httpUrl` are three vendors' names for one field, and the wrong
one fails silently at client startup.

Cursor — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`:

    {
      "mcpServers": {
        "quickerfile": {
          "url": "https://www.quickerfile.com/api/mcp",
          "headers": { "Authorization": "Bearer qf_live_..." }
        }
      }
    }

Windsurf — `~/.codeium/windsurf/mcp_config.json`, same shape with `serverUrl`
in place of `url`.

Gemini CLI — `~/.gemini/settings.json`, or `.gemini/settings.json` for one
project, same shape with `httpUrl` (`url` is the SSE field).

Antigravity — `~/.gemini/config/mcp_config.json`, or `.agents/mcp_config.json`
for one workspace, same shape with `serverUrl`. It ignores `url` and `httpUrl`.

VS Code — `.vscode/mcp.json`. The top-level key is `servers`, not
`mcpServers`, and the transport is named:

    {
      "servers": {
        "quickerfile": {
          "type": "http",
          "url": "https://www.quickerfile.com/api/mcp",
          "headers": { "Authorization": "Bearer qf_live_..." }
        }
      }
    }

Codex CLI — export the key as QUICKERFILE_API_KEY, then:

    codex mcp add quickerfile --url https://www.quickerfile.com/api/mcp \
      --bearer-token-env-var QUICKERFILE_API_KEY

The flag is `--bearer-token-env-var`; the abbreviated form is rejected. It
writes a `[mcp_servers.quickerfile]` block with `url` and
`bearer_token_env_var` into `~/.codex/config.toml`.

Devin — Settings, Connections, MCP servers, Add a custom MCP. Transport HTTP,
https://www.quickerfile.com/api/mcp as the URL, authentication Auth Header with key
`Authorization` and value `Bearer qf_live_...`. Requires the Manage MCP
Servers permission, which is an organisation admin.

ChatGPT — no MCP connector. Developer mode (custom MCP, read and write) is on
Plus, Pro, Business, Enterprise and Edu, so the plan is not the blocker;
authentication is, because a connector takes OAuth or no auth and never an API
key. The route that works today is a Custom GPT: Configure, Create new action,
Import from URL, https://www.quickerfile.com/api/v1/openapi.json, authentication API Key with
auth type Bearer. An Action sends text only and under 100,000 characters, so it
files a receipt with the `url` field of the JSON body below, never `file`. An
Action also gives up after 45 seconds; Quickerfile's own budget is 60, so a
large file on a slow host can time out on the ChatGPT side first. Nobody has
built one against this yet.

Gemini's consumer app supports no custom tools of any kind. There is no route
there, today or planned.

A local stdio MCP server exists in the Quickerfile repository but is not
published, so there is no public install command for it.

## 3. File one receipt

Over MCP, call the `file_receipt` tool with `base64` or `url`. Optional:
`filename`, `content_type`, `idempotency_key`, `redact`. There is no
`path` argument — the server cannot read the caller's filesystem. A `url`
is refused unless it resolves to a public internet address.

Over REST, with the bytes:

    curl https://www.quickerfile.com/api/v1/receipts \
      -H "Authorization: Bearer $QUICKERFILE_API_KEY" \
      -F file=@receipt.pdf

Over REST, with a link — the form a text-only caller can produce:

    curl https://www.quickerfile.com/api/v1/receipts \
      -H "Authorization: Bearer $QUICKERFILE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://example.com/lunch.pdf"}'

## 4. Redact one document

Over MCP, call `redact_document` with `base64` or `url`. Optional:
`profile` (`receipt`, `invoice`, `electricity-bill`), `custom` (a
list of extra terms to black out, at least 3 characters each), `keep` (values
to leave legible), `ocr`, `filename`, `content_type`,
`idempotency_key`.

Over REST:

    curl https://www.quickerfile.com/api/v1/redact \
      -H "Authorization: Bearer $QUICKERFILE_API_KEY" \
      -F file=@electricity-bill.pdf \
      -F profile=electricity-bill \
      -F custom="Anna Testsson"

To redact and file in one call, set `redact` on POST /api/v1/receipts. The
redaction runs first, so the model reads the redacted document and never the
original, and the file that comes back is the redacted one.

What is found: personnummer, organisationsnummer, IBAN, bankgiro, plusgiro, OCR
references, card numbers, emails, phone numbers, postal addresses, person names,
and customer, agreement, facility and meter numbers. Checksums for the numeric
ones, the printed label for the rest, the block for a recipient address that has
no label at all, plus whatever the caller passes in `custom`.

Every organisation number is redacted, the supplier's included — a sole trader's
is their personnummer and a company customer's is on the recipient side of the
page. Pass the supplier's in `keep` to hold it back; digits are compared
without separators.

Never touched: amounts, dates, VAT, tax rates, line items, kWh, prices, tariffs,
the invoice number and the meter reading.

What "redacted" means here: every page is rendered to a bitmap and the bars are
painted onto the pixels. A rectangle drawn over live PDF text is a graphic and
the words underneath it are still extractable; this leaves no text layer at all.
The output is a picture — larger than the input, and not searchable.

## API

Base URL: https://www.quickerfile.com
Spec: https://www.quickerfile.com/api/v1/openapi.json (OpenAPI 3.1)
Reference: https://www.quickerfile.com/developers

- POST /api/v1/receipts — file one receipt. multipart/form-data with a `file`
  field, or JSON with the file base64 encoded in `file`, or JSON with a public
  `url` the server downloads. In JSON, send exactly one of `file` and `url`;
  both together is a 400. A `url` is refused unless it resolves to a public
  internet address, every redirect is re-checked, and the read is capped at
  10 MB whatever Content-Length claims. Honours an
  `Idempotency-Key` header for 24 hours; the key is bound to the bytes it was
  first used with.
- POST /api/v1/redact — black out the personal data in one document. Same three
  ways in as filing. Body fields: `profile`, `custom`, `ocr`. Returns
  `redacted_url`, `content_type`, `size_bytes`, `pages` and a
  `report` saying what kind of thing was covered and where — never what it
  was. Body fields also take `keep`. Costs one receipt from the allowance,
  like filing one.
- GET /api/v1/receipts/{id} — read a filed receipt back, for 24 hours.
- GET /api/v1/usage — plan, monthly allowance, receipts used, period end.
- POST /api/mcp — the MCP endpoint above. GET and DELETE return 405.

## Limits

- Accepted formats: PDF, JPEG, PNG, WEBP, HEIC, HEIF. Maximum 10 MB per file.
- Redaction over the API accepts PDF, JPEG and PNG only, up to 20
  pages. WEBP, HEIC and HEIF are refused there rather than passed through
  unredacted; the browser page at https://www.quickerfile.com/redact takes WEBP as well.
  A photo or scan, and a PDF page that is only an image, need `ocr: true`;
  pages nothing could be read from come back in `pages_without_text`.
- Request bodies are capped at 10 MB. base64 is a third larger than the file it
  carries, so a base64 receipt tops out at about 7.4 MB; use
  `url` on either surface, or multipart over REST, for anything bigger. Past the cap
  the answer is `413 payload_too_large`, not a parse error. That is decided
  from `Content-Length`: send one, or an over-cap body is truncated and comes
  back as a parse error instead.
- One receipt per call. No batch endpoint.
- JPEG and PNG are returned as a single-page PDF wrapping the image. WEBP, HEIC
  and HEIF are returned in their original format, renamed, with
  `metadata_embedded: false`.
- Receipt records are scheduled to expire after 24 hours. Download links point
  to public, unguessable URLs and may remain reachable until cleanup succeeds;
  treat them as secrets. A 100-request rolling daily limit applies only on
  deployments with rate limiting configured.

## Pricing

Receipts filed through MCP, through REST and through the dashboard draw on one
monthly allowance, and so do redactions — one document redacted costs one
receipt. There is no separate API plan and no per-call charge.

- Free — $0 — 5 receipts per month
- Starter — $10/month — 250 receipts per month
- Pro — $20/month — 750 receipts per month
- Business — $50/month — 2,500 receipts per month

## Errors

Failures return `{ "error": { "type": ..., "message": ... } }`. Branch on type.

- 400 invalid_request — malformed body, or an unsupported file format
- 401 unauthorized — key missing, malformed or revoked
- 402 quota_exceeded — the month's receipts are used up; body carries plan, limit, used
- 404 not_found — no such receipt for this account, or it is past its 24 hours
- 422 unprocessable_file — readable file, but no vendor, date and total in it
- 422 idempotency_key_reuse — that Idempotency-Key was already used for different
  bytes; use a new key rather than receiving the earlier receipt
- 413 payload_too_large — the file is over 10 MB, or the request body is
- 429 rate_limited — past the burst limit, where rate limiting is configured:
  100/day per account, and on /api/mcp a further 60/min per API key
- 500 server_error — read but not stored or recorded; not counted against quota

Over MCP everything past authentication arrives as a tool error carrying the
same `type`. 401, 413 and the per-key 429 are refused before a tool runs and
arrive as JSON-RPC protocol errors with the matching HTTP status.