API reference

Base URL https://api.vantafold.ai. All requests are JSON over HTTPS and require a bearer token. The API is versioned in the path; /v1 is current and is supported until at least 2029.

Reason

POST /v1/reason

Send an input to a model and get a response. This is the endpoint you will use most — it covers text, tool calling, structured output, and streaming.

Parameters

Name	Type	Description
`model`required	string	A model name from the catalog, or `"auto"` to let the router choose.
`input`required	string \| array	A prompt string, or an array of message objects with `role` and `content`.
`tools`optional	array	Tool definitions the model may call. Normalised across providers.
`routing`optional	object	Routing policy: `optimize`, `max_cost_usd`, `max_latency_ms`, `min_quality`, `fallback`.
`response_format`optional	object	Set `{"type": "json_schema"}` with a schema to constrain output.
`stream`optional	boolean	Return server-sent events instead of a single response. Defaults to `false`.
`metadata`optional	object	Arbitrary key-value tags recorded on the trace and available for cost attribution.
`cache`optional	boolean	Prompt prefix caching. Defaults to `true`.

Request

POST api.vantafold.ai/v1/reason

response = client.reason(
    model="auto",
    input=[{"role": "user", "content": "Reconcile these two ledgers."}],
    tools=[ledger_lookup],
    routing={"optimize": "quality", "max_latency_ms": 4000},
    metadata={"project": "billing-agent"},
)

const response = await client.reason({
  model: "auto",
  input: [{ role: "user", content: "Reconcile these two ledgers." }],
  tools: [ledgerLookup],
  routing: { optimize: "quality", max_latency_ms: 4000 },
  metadata: { project: "billing-agent" },
});

curl https://api.vantafold.ai/v1/reason \
  -H "Authorization: Bearer $VANTAFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "input": [{ "role": "user", "content": "Reconcile these two ledgers." }],
    "routing": { "optimize": "quality", "max_latency_ms": 4000 },
    "metadata": { "project": "billing-agent" }
  }'

Response

200 OK

{
  "id": "req_8f2c41a9",
  "object": "reason.response",
  "model": "frontier-lg",
  "output_text": "The 4,120.00 variance is a timing difference...",
  "tool_calls": [
    { "name": "ledger_lookup", "arguments": { "period": "2026-07" }, "duration_ms": 402 }
  ],
  "usage": {
    "input_tokens": 4210, "cached_input_tokens": 3800,
    "output_tokens": 186, "cost_usd": 0.0154
  },
  "route": {
    "requested": "auto", "selected": "frontier-lg", "attempts": 1,
    "reason": "quality objective; tools required"
  },
  "trace_id": "tr_5b1d9e0c",
  "created_at": "2026-08-19T09:14:22Z"
}

Embeddings

POST /v1/embeddings

Turn text into vectors. Batches of up to 2,048 inputs per request.

Parameters

Name	Type	Description
`model`required	string	An embedding model from the catalog.
`input`required	string \| array	One string, or an array of up to 2,048 strings.
`dimensions`optional	integer	Truncate output vectors to this many dimensions.
`metadata`optional	object	Tags recorded on the trace.

Request

POST api.vantafold.ai/v1/embeddings

vectors = client.embed(
    model="embed-3-large",
    input=["net 30 from invoice date", "payable within thirty days"],
)

print(len(vectors.data), vectors.usage.input_tokens)

const vectors = await client.embed({
  model: "embed-3-large",
  input: ["net 30 from invoice date", "payable within thirty days"],
});

console.log(vectors.data.length, vectors.usage.input_tokens);

curl https://api.vantafold.ai/v1/embeddings \
  -H "Authorization: Bearer $VANTAFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "embed-3-large", "input": ["net 30 from invoice date"] }'

Response

200 OK

{
  "object": "list",
  "model": "embed-3-large",
  "data": [
    { "index": 0, "embedding": [0.0142, -0.0311, 0.0087, "..."] },
    { "index": 1, "embedding": [0.0138, -0.0294, 0.0091, "..."] }
  ],
  "usage": { "input_tokens": 14, "cost_usd": 0.0000003 },
  "trace_id": "tr_9c02fa17"
}

List models

GET /v1/models

Every model available to your account, with context windows, capabilities, and current rates. Filterable, and safe to cache for an hour.

Parameters

Name	Type	Description
`capability`optional	string	Filter by `tools`, `vision`, `json`, or `embed`.
`provider`optional	string	Filter by provider slug.
`max_input_price`optional	number	Maximum USD per 1M input tokens.
`limit`optional	integer	Page size, 1–200. Defaults to 50.

Request

GET api.vantafold.ai/v1/models

curl "https://api.vantafold.ai/v1/models?capability=tools&max_input_price=1.0" \
  -H "Authorization: Bearer $VANTAFOLD_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "oss-70b-instruct",
      "provider": "open-weights",
      "context_window": 128000,
      "capabilities": ["tools", "json", "stream"],
      "price_per_1m": { "input": 0.35, "output": 0.90 },
      "status": "available"
    }
  ],
  "has_more": true
}

Get trace

GET /v1/traces/{trace_id}

Retrieve the full trace for a request: every span, the routing decision, token counts, and cost. Retention follows your plan.

Parameters

Name	Type	Description
`trace_id`required	string	The `trace_id` returned with the response.
`include_payloads`optional	boolean	Include prompt and completion text. Ignored in zero-retention mode.

Request

GET api.vantafold.ai/v1/traces/{trace_id}

curl https://api.vantafold.ai/v1/traces/tr_5b1d9e0c \
  -H "Authorization: Bearer $VANTAFOLD_API_KEY"

Response

200 OK

{
  "trace_id": "tr_5b1d9e0c",
  "duration_ms": 1284,
  "status": "completed",
  "route": { "requested": "auto", "selected": "frontier-lg", "attempts": 1 },
  "usage": { "input_tokens": 4210, "output_tokens": 186, "cost_usd": 0.0154 },
  "spans": [
    { "name": "gateway.auth", "start_ms": 4, "duration_ms": 8 },
    { "name": "router.select", "start_ms": 12, "duration_ms": 31 },
    { "name": "model.frontier-lg", "start_ms": 46, "duration_ms": 1180 },
    { "name": "tool.ledger_lookup", "start_ms": 214, "duration_ms": 402 }
  ]
}

Usage

GET /v1/usage

Aggregated spend and token counts for a period, grouped by model, project, or any tag you send. This is the endpoint behind the dashboard, and the numbers match your invoice.

GET /v1/usage

curl "https://api.vantafold.ai/v1/usage?start=2026-08-01&end=2026-08-19&group_by=model" \
  -H "Authorization: Bearer $VANTAFOLD_API_KEY"

Conventions

Authentication

Send Authorization: Bearer <key> on every request. Keys are scoped to a project and may be restricted to specific models or a spend ceiling.

Errors

Errors return a JSON body with a stable code, a human message, and, where relevant, the attempts the router made.

529

{
  "error": {
    "code": "all_routes_degraded",
    "message": "Every model in the fallback chain failed.",
    "attempts": [
      { "model": "frontier-lg", "status": 529, "duration_ms": 1240 },
      { "model": "reason-pro", "status": 500, "duration_ms": 980 }
    ],
    "trace_id": "tr_44a1c8de"
  }
}

Versioning

Breaking changes ship behind a new path version and are announced in the changelog with a 12-month deprecation window. Additive changes — new fields, new models, new event types — can appear in /v1 at any time, so parse defensively and ignore unknown fields.

PreviousDocumentation NextModel catalog

Product

Developers

Company

Reason

Parameters

Request

Response

Embeddings

Parameters

Request

Response

List models

Parameters

Request

Response

Get trace

Parameters

Request

Response

Usage

Conventions

Authentication

Errors

Versioning