Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.reasonblocks.com/llms.txt

Use this file to discover all available pages before exploring further.

The REST API follows a deliberate versioning policy so external integrators can pin against a stable surface.

​
The /v1/ contract

All public routes are mounted under /v1/. This is the surface external integrators should target. Anything under /v1/ follows these rules:
  • Request schemas only grow in backwards-compatible ways — new optional fields are fine, new required fields are not.
  • Response schemas only grow additively. Removing or renaming a field is a breaking change.
  • HTTP status code semantics are stable per route.
  • Path parameter names are stable. Renaming a path parameter is a breaking change.
When a breaking change is needed, the new contract will be mounted under /v2/ alongside /v1/, with a deprecation window announced before sunset.

​
Unversioned legacy aliases

For back-compat with already-deployed SDK clients that hardcode paths like POST /traces/retrieve, every public route is also mounted at its historical unprefixed location. These aliases:
  • Are functionally identical to the /v1/ route — same handler.
  • Are hidden from the OpenAPI schema. /docs only shows /v1/.
  • May be removed in a future release after a deprecation window. New integrations must not depend on them.
If you’re starting a fresh integration today, target /v1/.... Treat any unversioned response as legacy SDK back-compat, not a stable surface.

​
SDK pinning

The Python SDK (reasonblocks) currently issues requests against the unversioned paths. When the SDK migrates to /v1/:
  1. The SDK minor version bumps.
  2. The internal HTTP clients prefix paths with /v1.
  3. REASONBLOCKS_BASE_URL semantics stay unchanged — the prefix is a client-side path concern, not a base URL one.
Until that migration ships, the unversioned aliases are load-bearing and remain mounted.

​
OpenAPI and client code generation

Both reflect only the /v1/ surface. Code generation against this spec is safe — the unversioned aliases never appear there, so generated clients exclusively target /v1/.