OpenAPI spec

Every Curva server serves an OpenAPI 3.1 description of its HTTP API at GET /openapi.json. It covers every route, request option, question type, model plan, response field and error, with examples. It holds no data, so it is served without an API key.

curl http://localhost:7777/openapi.json

Postman and Insomnia

• Postman: Import → Link → http://localhost:7777/openapi.json (or your server’s URL). Postman creates a collection with a request per route. Set the collection’s Authorization to Bearer Token with your curva_… key.
• Insomnia: Create → Import → URL, and paste the same address. Put the key in the collection’s Bearer auth.

Both keep the spec’s examples, so POST /v1/decide arrives with a working support-ticket body.

Generate a client in any language

OpenAPI Generator builds clients for Go, Java, C#, Ruby, PHP, Rust, Swift, Kotlin and more:

curl -o curva-openapi.json http://localhost:7777/openapi.json
npx @openapitools/openapi-generator-cli generate -i curva-openapi.json -g go -o ./curva-go

Swap -g go for any generator name (java, csharp, ruby, php, rust, kotlin, …). For Python and TypeScript, the hand-written SDKs are simpler: see the Python SDK and TypeScript.

Unions

A few fields accept more than one shape: model (an id, a fallback list, or a council, cascade or race object), debias (true/false or "auto"), a question (by type) and an answer’s probabilities (per option or per level). Generators model these as oneOf types, which some languages make verbose. Where that gets in the way, send the request body as plain JSON.

Validate or explore it

uvx --from openapi-spec-validator openapi-spec-validator curva-openapi.json

Any OpenAPI viewer (Swagger UI, Redoc, Scalar) renders it as browsable docs, and API gateways and tools such as Kong, Apigee or Postman monitors can import it too.

The spec follows the frozen v1 contract: new versions only add optional fields and routes, so generated clients keep working. The narrative reference is HTTP API.