Skip to content

Tools

OpenAPI specification

All 10 endpoints as a machine-readable OpenAPI 3 document, generated rather than written.

Spec
curl https://api.cresva.ai/v1/openapi.json -o cresva-openapi.json

Where it comes from

Nothing in the specification is hand-written. Every path, parameter, enum, default and response shape is read out of the zod objects in lib/api/v1/schemas.ts, which is the same object the handler validates each request against.

Pipeline
lib/api/v1/schemas.ts        the zod objects the handler parses every request through        |        +--> /v1/openapi.json      the specification        |         |        |         +--> cresva      the generated TypeScript client on npm        |         |        |         +--> your client generated in any language        |        +--> cresva.ai/docs        these pages

A contract test asserts that every route under /api/v1 appears in the specification, so adding an endpoint without a schema fails the build rather than shipping undocumented.

What you can do with it

  • Generate a client in your own language. See SDKs.
  • Import it into Postman, Insomnia, Bruno or an HTTP client that reads OpenAPI, and get every endpoint with its parameters already filled in.
  • Diff it in CI against the copy you generated your client from, and find out that a field changed before your users do.

What the specification promises

One distinction is worth stating because it affects how much you should trust the document.

  • Request schemas are enforced. The handler parses every request through the same object the spec was generated from, so a request the spec says is invalid will be rejected.
  • Response schemas are described. They document the 200 shape and are deliberately not used to validate outgoing payloads. A reader who assumed responses were schema-checked would trust the document more than it has earned.

Rows that vary by provider are typed honestly

Metric rows are provider-shaped and vary with the metrics requested, so the specification says object rather than inventing a fixed row type the fetcher does not guarantee. That is a deliberate accuracy rather than a gap.