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.