API Overview

Base URL

https://api.factum.pyragogy.org

⬇ Download OpenAPI Spec (JSON)

The API is built on FastAPI/OpenAPI. Marketplace deployment is a proxied distribution channel; the public URL and authentication injection may differ from the origin API contract.

Authentication

Business endpoints require:

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

The backend is fail-closed: a missing or invalid key returns 401 Unauthorized. 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 input, request-scoped
doc_type	enum	no	auto, fattura, f24, generico; default auto
async_mode	boolean	no	Async mode; not valid with text
callback_url	HTTP URL	no	Webhook for async. Only with async_mode=true

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

Upload

POST /v1/uploads accepts a single multipart field:

file=<XML or PDF>

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

The transport and semantic 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 environment-configurable. When active (X-Tier header: free | basic | pro), the middleware may emit 429 Too Many Requests.

Current limits (from app/services/ratelimit.py):

Tier	Limit	Window
free	60 req/min	1 min
basic	100 req/min	1 min
pro	1000 req/min	1 min

Response Contracts

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 ID

The backend currently 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, not a fabricated feature.