Contents

Use the REST API

The tools your assistant calls over MCP are also plain HTTP endpoints, for scripts and for programs that do not speak MCP. Same tools, same prices, same refusals.

https://mairies.vosfichiers.com/api/v1

Authentication

Create a key under API keys. It is shown once and starts with sk_. Send it on every call:

Authorization: Bearer sk_...

Keep the key out of your source code and out of a browser: anyone who holds it spends your credits. Revoke a key that leaked; it stops working within a minute.

Call a tool

POST https://mairies.vosfichiers.com/api/v1/<tool> with the arguments as a JSON object. The page of each tool in the documentation lists its fields and gives a ready-made request. The example below calls account-status, a free tool every account has: it takes no argument and tells what is left to spend.

curl -X POST https://mairies.vosfichiers.com/api/v1/account-status \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

A success answers 200. The body is the output of the tool, as described on its page:

{
  "plan": "Free",
  "allowance_remaining": 80,
  "purchased_credits": 0,
  "credits_available": 80,
  "monthly_credits": 100,
  "renews_at": "2026-12-01T00:00:00+00:00",
  "billing_url": "https://mairies.vosfichiers.com/app/billing"
}
Response header Meaning
X-Request-Id Identifier of this call. Quote it when you write to support
X-Credits-Charged Credits this call cost
X-Credits-Remaining Credits left after it, on a paid tool
Idempotent-Replay true when the answer was replayed from an earlier call with the same idempotency key

A tool that takes no argument accepts an empty body or {}.

Endpoints

Method and path What it does
POST /api/v1/<tool> Run a tool
GET /api/v1/tools The tools your key can see, with their schemas and prices
GET /api/v1/openapi.json The same catalogue as an OpenAPI 3.1 document
GET /api/v1/jobs/<job_id> State of a job started by a long-running tool
GET /api/v1/me Your plan, balances and rate limit

Retry safely with an idempotency key

A network error can hide whether a call went through. Send an Idempotency-Key header of your choice (a UUID is fine) with the call, and send the same key again when you retry:

curl -X POST "https://mairies.vosfichiers.com/api/v1/<tool>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0d1e-6c1b-4f0a-9d53-2f7a1c0e9b11" \
  -d '<arguments as JSON>'
  • Same key, same body, first call succeeded: you receive the stored answer, with Idempotent-Replay: true, and you are not charged again.
  • Same key, different body: 422 idempotency_conflict.
  • Same key while the first call still runs: 409 idempotency_in_progress.

Only successes are stored, for 24 hours. A refused call costs nothing and can simply be sent again.

Long-running tools

A tool marked long-running answers at once with a job:

{"job_id": "6f1c2f0e-8f5b-4f7e-9d0a-3f0c1b2a4d5e", "status": "queued"}

Ask for its state every one to two seconds until status is succeeded or failed:

curl https://mairies.vosfichiers.com/api/v1/jobs/6f1c2f0e-8f5b-4f7e-9d0a-3f0c1b2a4d5e \
  -H "Authorization: Bearer $API_KEY"
{
  "job_id": "6f1c2f0e-8f5b-4f7e-9d0a-3f0c1b2a4d5e",
  "tool": "company-report",
  "status": "running",
  "progress": 40,
  "message": "Fetching filings",
  "result": null,
  "error": null,
  "created_at": "2026-11-13T10:00:00+00:00",
  "finished_at": null
}

status is one of queued, running, succeeded, failed. On succeeded, read result. On failed, read error: the credits of the call were given back. A job is visible to the account that started it; any other identifier answers 404 not_found.

Over MCP the same job is followed with the tool job-status, which takes the job_id and answers with this same object.

When a call is refused

The body always has the same shape, and the HTTP status tells the kind of refusal:

{
  "error": {
    "code": "invalid_input",
    "message": "Invalid arguments. text: Field required",
    "request_id": "3f9c2a7d41be4c0f9a61d2e7c5b80a14",
    "fields": [{"field": "text", "message": "Field required"}]
  }
}

Every code, what it means and what to do is in Errors and quotas.