API builder

Endpoint API

Reference for calling published endpoints at www.scalaix.com/<project>/<collection>/<endpoint>.

Calling an endpoint

POST https://www.scalaix.com/<project>/<collection>/<endpoint>[?version=<n>]
Authorization: Bearer sx_...
Content-Type: application/json

version is optional; the latest published version answers by default. The key must allow the endpoints mode and, if it lists collections, this collection.

Request body

{
  "inputs": { "ticket": { "subject": "Charged twice", "body": "..." } },
  "options": { "model": null, "cache": true }
}

Field	Notes
`inputs`	Required. The endpoint's variables. See Variables and templates.
`options.model`	Optional. Run with another catalog model (subject to the key's allowed models). `null` uses the endpoint's model.
`options.cache`	Optional. `false` skips the cache for this call.

The body can be up to 1 MB.

Response 200

{
  "data": { "category": "bug", "priority": 4, "tags": ["login"] },
  "model": "gpt-4o-mini",
  "version": 3,
  "cached": false,
  "usage": { "input_tokens": 312, "output_tokens": 41, "cost_usd": 0.00012 },
  "request_id": "req_8f2c41d07a"
}

Field	Notes
`data`	Parsed JSON (format `json`), a string (`text`, `xml`) or `{"columns", "rows"}` (`csv`). An array of those when the endpoint has `variations` above 1.
`model`	The model that answered, after fallback.
`version`	The version that ran.
`cached`	`true` when the answer came from cache.
`usage`	Tokens and cost of this call.
`request_id`	Same as the `X-Scalaix-Request-Id` header.

The response also carries the X-Scalaix-Model, X-Scalaix-Cache and X-Scalaix-Fallbacks headers described in the Gateway API.

Errors

Status	`type`	When
400	`invalid_request`	The body isn't JSON or has no `inputs`.
401	`invalid_api_key`	Missing, unknown, revoked or expired key.
402	`insufficient_quota`	Out of credits, or the key's budget is spent.
403	`forbidden`	The key doesn't allow endpoints, this collection, this origin or IP.
404	`not_found`	Unknown project, collection, endpoint or version, or nothing published yet.
413	`invalid_request`	The body is over 1 MB.
422	`invalid_inputs`	Inputs don't match the variables. The message has the path: `inputs.ticket.subject: required`.
429	`rate_limited`	Over the key's requests per minute. See `Retry-After`.
501	`not_implemented`	The endpoint uses a `file` variable (not available yet).
502	`upstream_error`	The model failed and no fallback succeeded.
502	`invalid_model_output`	The answer didn't match the output schema after one repair attempt.
504	`timeout`	The model didn't answer in time.

Examples

import os, requests

resp = requests.post(
    "https://www.scalaix.com/acme/support/classify-ticket",
    headers={"Authorization": f"Bearer {os.environ['SCALAIX_API_KEY']}"},
    json={"inputs": {"ticket": {"subject": "Charged twice", "body": "Billed two times in March."}}},
    timeout=60,
)
if resp.status_code == 422:
    print("Fix the inputs:", resp.json()["error"]["message"])
resp.raise_for_status()
print(resp.json()["data"])

const res = await fetch("https://www.scalaix.com/acme/support/classify-ticket?version=3", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SCALAIX_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ inputs: { ticket: { subject: "Charged twice", body: "Billed two times in March." } } }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data.category, body.data.priority);

Every published collection also has generated docs with examples built from its own variables: https://www.scalaix.com/<project>/<collection>.