Quickstart

This guide takes you from an empty terminal to a typed decision. It uses the public decision endpoint and inline choices, so you do not need a dashboard, SDK, or stored catalog to begin.

Before you begin

An HTTP client such as cURL, fetch, or Python requests.
A question with a finite set of valid answers.

The free decision endpoint does not require an API key. The examples below intentionally send no Authorization header, so you can make your first request without a dashboard, account console, or credential.

Send a decision

Choose the model and outcomes

Pick a model identifier, write the context as input, and write the question as instruction. Provide at least two unique choices.

Send JSON to the decisions endpoint

Use POST https://api.aspaslabs.com/v1/decisions with Content-Type: application/json.

curl https://api.aspaslabs.com/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "goldenfish-g1",
    "input": "forgot my password",
    "instruction": "Which category applies?",
    "choices": [
      "reset_password",
      "billing",
      "cancel_account",
      "technical_issue"
    ]
  }'

const response = await fetch(
  "https://api.aspaslabs.com/v1/decisions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "goldenfish-g1",
      input: "forgot my password",
      instruction: "Which category applies?",
      choices: [
        "reset_password",
        "billing",
        "cancel_account",
        "technical_issue"
      ]
    })
  }
);

const decision = await response.json();
console.log(decision.output.choice);

import requests

response = requests.post(
    "https://api.aspaslabs.com/v1/decisions",
    json={
        "model": "goldenfish-g1",
        "input": "forgot my password",
        "instruction": "Which category applies?",
        "choices": [
            "reset_password",
            "billing",
            "cancel_account",
            "technical_issue",
        ],
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["output"]["choice"])

Read the typed result

A successful response contains the request ID, the model, the selected choice, its confidence, a probabilities object, and token usage.

200 OK

{
  "id": "dec_01K7Y...",
  "object": "decision",
  "model": "goldenfish-g1",
  "output": {
    "choice": "reset_password",
    "confidence": 0.9489,
    "probabilities": {
      "reset_password": 0.9489,
      "billing": 0.0001,
      "cancel_account": 0.0001,
      "technical_issue": 0.0009
    }
  },
  "usage": { "input_tokens": 13 }
}

Request rules

The request must include model, input, and instruction. It must include exactly one of:

choices: an inline array containing 2–300 unique, non-empty strings.
catalog: the ID of an existing catalog.

choices and catalog cannot be sent together. The model is selected in the body, not by changing the route. The free path uses inline choices and does not require a bearer key. A catalog can be used after a protected catalog has been created with the catalog API.

Do not treat confidence as a business rule by itself. If your product needs a fallback for uncertain results, define that threshold in your application and test it against your own data.

What to do next

Understand the decision contract

Learn how choices, catalogs, confidence, and probabilities fit together.

Use protected catalog endpoints

Learn when a bearer key is needed for catalog creation and management.

Create a reusable catalog

Move stable choices out of individual requests and reuse them by ID.

Handle errors and retries

Implement request IDs, rate-limit backoff, and actionable error handling.

Get started

Concepts

Guides

API reference

Resources

Before you begin

Send a decision

Request rules

What to do next

Understand the decision contract

Use protected catalog endpoints

Create a reusable catalog

Handle errors and retries

​Before you begin

​Send a decision

​Request rules

​What to do next

Understand the decision contract

Use protected catalog endpoints

Create a reusable catalog

Handle errors and retries

Before you begin

Send a decision

Request rules

What to do next