API Reference

Authentication

Most endpoints require a license key in the Authorization header:

Authorization: Bearer PYV-XXXX-XXXX-XXXX

Health & Status

GET /health

Returns API health and version.

curl https://api.pyvorin.com/health

License API

POST /v1/license/check

Validate a license key. The raw key is hashed (SHA-256) before transmission.

POST /v1/license/summary

Get a summary of the stored license.

Compile API

POST /v1/compile

Submit a compile job. Returns a job_id for async polling.

Field	Type	Required	Description
source	string	Yes*	Raw Python source (only if upload enabled).
workload_hash	string	Yes*	SHA-256 hash of source.
function_name	string	No	Function to compile. Empty = whole module.
backend	string	No	Default: native.
opt_level	int	No	0–3. Default: 3.
strict	bool	No	Fail on warnings. Default: false.
bundle	object	No	Project bundle for local imports.

* Either source or workload_hash must be provided.

GET /v1/compile/jobs/{job_id}

Poll compile job status. Status values: queued, compiling, complete, failed, timeout.

GET /v1/compile/jobs

List recent jobs. Query params: limit, status.

GET /v1/artifacts/{artifact_id}/download

Download compiled artifact ZIP.

Usage API

POST /v1/usage/event

Send a usage event. Events are non-billable if correctness_match=false, fallback_used=true, or backend_used != "native".

Response Codes

Code	Meaning
200	Success.
202	Accepted (compile job queued).
400	Bad request.
401	Unauthorized.
403	Forbidden.
422	Unprocessable entity.
429	Rate limited.