Getting Started

Getting Started

API

MCP Server

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.json

The 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"
FormatOpenAPI 3.1 (JSON)
Auth schemehttp / bearer — send Authorization: Bearer tr_...
Serverhttps://trellis2.app/api/v1
EndpointsPOST /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 running fallback — see Tasks & Polling
  • the 60 requests/minute budget and its headers — see Rate Limits

Table of Contents

OpenAPI Spec & SDKs
Get the spec
Import into an API client
Generate a typed client
Schema stability