OpenAPI Spec & SDKs
Import the spec into Postman, Insomnia or Swagger UI, or generate a typed client
OpenAPI Spec & SDKs
Trellis 2 publishes a machine-readable OpenAPI 3.1 description of the whole
/api/v1 surface. Everything in the API Reference
is generated from it.
Get the spec
curl https://trellis2.app/api/openapi.json -o trellis2-openapi.jsonThe endpoint is public — no API key required — so you can pull it in CI and diff it between releases:
# fail the build if the public contract changed unexpectedly
curl -s https://trellis2.app/api/openapi.json > openapi.latest.json
diff -q openapi.pinned.json openapi.latest.json || echo "API contract changed"| Format | OpenAPI 3.1 (JSON) |
| Auth scheme | http / bearer — send Authorization: Bearer tr_... |
| Server | https://trellis2.app/api/v1 |
| Endpoints | POST /3d/generations, GET /tasks/{taskId}, GET /models |
Import into an API client
Postman — Import → File (or Import → Link with the URL above). The bearer scheme is filled in as a collection variable, so set it once and every request inherits it.
Insomnia — Create → Import From → URL, paste the spec URL.
Swagger UI / Redoc — point them at the JSON URL directly:
<redoc spec-url="https://trellis2.app/api/openapi.json"></redoc>Prefer clicking through requests? The API Reference pages have a built-in playground that uses the same spec, with your key entered in the browser only.
Generate a typed client
Any OpenAPI generator works. The spec is small, so generated code is readable rather than overwhelming.
# TypeScript (fetch-based)
npx openapi-typescript https://trellis2.app/api/openapi.json \
-o src/types/trellis2.d.ts
# Python
openapi-generator-cli generate \
-i https://trellis2.app/api/openapi.json \
-g python \
-o ./trellis2-client// with the generated types, the response is typed end to end
import type { paths } from './types/trellis2';
type Task =
paths['/tasks/{taskId}']['get']['responses']['200']['content']['application/json'];Schema stability
The spec is the contract — field names in the reference pages, in the response examples throughout these docs, and in the JSON you receive are the same names, deliberately. If a field is going to change, the spec changes first.
Two things the spec does not describe, because they are behavioural rather than structural:
- the 55-second sync cap and the
runningfallback — see Tasks & Polling - the 60 requests/minute budget and its headers — see Rate Limits