API overview¶
Base URL for the hosted service: https://api.cutweaver.io
Dedicated deployments expose the same JSON contract on your private base URL.
All public endpoints return JSON. Request bodies for POST endpoints should be sent as application/json.
The public contract is versioned under /api/v1/... and evolves additively.
Endpoints¶
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /health |
none | Liveness probe |
| GET | /api/v1/info |
none | Service metadata and endpoint catalog |
| GET | /api/v1/schema |
none | Machine-readable discovery document |
| GET | /api/v1/runtime |
none | Active host/port, CLI flags, client identity policy, and state-store policy |
| POST | /api/v1/request-key |
none | Issue or reuse the free evaluation key |
| POST | /api/v1/solve |
optional | Solve a cutting request; anonymous access is quota-limited |
| GET | /api/v1/usage |
required | Current quota state for a keyed plan |
Versioning policy¶
- Current public contract version:
v1. - New optional fields can be added without changing the version.
- Breaking changes require a new contract version.
- Request payloads remain strict for the target contract version: undocumented fields are rejected.
Discovery¶
Use GET /api/v1/schema when you need machine-readable metadata for:
- canonical top-level request fields,
- supported strategies,
- transport limits,
- hosted auth and quota tiers.
The human-readable JSON contract page is rendered from the canonical public contract source.
Runtime metadata¶
GET /api/v1/runtime publishes deployment metadata that affects operations but not the request JSON contract:
- active state DB path;
- SQLite state-store policy:
journalMode=wal,schemaVersion=2,busyTimeoutMs=5000,foreignKeys=true; - solve concurrency and queue limits;
- whether trusted proxy headers are enabled for client identity.
State-store schema version 2 adds an internal audit table for key lifecycle events. Key revocation is intentionally not exposed as a public HTTP endpoint.