API Overview

Base URL

https://api.factum.pyragogy.org

The API is FastAPI/OpenAPI-based. The marketplace deployment is a proxy distribution channel; its public request URL and authentication injection are not the same thing as the origin API contract.

Authentication

Business endpoints require:

X-API-Key: <your-api-key>

The backend is fail-closed: a missing or invalid API key returns 401 Unauthorized. The key comparison uses secrets.compare_digest.

Public endpoints:

• GET /health
• GET /status

Request sources

POST /v1/parse accepts exactly one source:

Field	Type	Required	Notes
job_id	UUID	XOR	Job returned by /v1/uploads
text	string	XOR	Stateless, request-scoped input
doc_type	enum	no	auto, fattura, f24, generico; default auto
async_mode	boolean	no	Async job mode; not valid with text
callback_url	HTTP URL	no	Only valid with async_mode=true

job_id and text are mutually exclusive and one must be present.

Uploads

POST /v1/uploads accepts a single multipart field:

file=<XML or PDF>

There is no separate required filename form field in the backend contract; FastAPI receives the filename as UploadFile.filename metadata.

The transport and semantic upload limit is 10 MiB (max_body_bytes and max_upload_bytes). Supported document classes are FatturaPA XML and invoice PDF.

Rate limiting

Rate limiting is configurable through environment settings and is not hard-coded as a public free/basic/premium contract in the Pydantic API schemas. Do not treat historical tier tables as an API guarantee. When enabled (header X-Tier: free | basic | pro), the middleware may emit 429 Too Many Requests.

The current configured limits (from app/services/ratelimit.py, not from Pydantic models):

Tier	Limite	Finestra
free	60 req/min	1 min
basic	100 req/min	1 min
pro	1000 req/min	1 min

Response layers

There are two distinct contracts:

1. DocumentResponse — ingestion/job metadata returned by /v1/uploads and /v1/uploads/{job_id}.
2. ParseResponse — parse execution metadata plus result: DocumentEnvelope | null.

DocumentEnvelope v2 is the canonical structured result inside ParseResponse.result. See Schemas.

Request IDs

The current backend accepts X-Request-Id on POST /v1/uploads and uses it as the RFC 7807 instance value when an upload error is generated.

A global X-Request-ID response header is not currently implemented across all routes. Do not document it as a universal guarantee until the backend adds and tests that middleware.

This is intentional documentation debt rather than an invented feature.