API referenceSend a case and typed questions. Get every answer back with its probability, in one call.

Quick start

One endpoint, POST /v1/systemone, at https://api.amos.scira.ai. No API key.

This request asks five questions about a support ticket, and its Response tab is the answer that came back. Every request is kept to improve the models; see Privacy.

No text is generated, so output_tokens is always 0. Try your own schema in the playground.

curl https://api.amos.scira.ai/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
  "state": {
    "ticket": "Hi, invoice INV-2231 for £306.00 was charged to my card twice this morning. Please refund one of them today.",
    "customer": {
      "plan": "pro",
      "since": "2024-03-02"
    }
  },
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for a refund?"
    },
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoices, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Plans, upgrades, new accounts"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": [
        "Can wait",
        "This week",
        "Today"
      ]
    },
    "mentions": {
      "type": "multi",
      "instructions": "Which details does the ticket mention?",
      "criteria": {
        "invoice number": null,
        "amount": null,
        "bank account": null
      }
    },
    "amount": {
      "type": "span",
      "instructions": "How much was charged?"
    }
  },
  "model": "amos-1-mini"
}'

Request

One case and the questions to ask about it.

statestring | object | array: Required. The case. Objects and arrays are read as JSON; name a field in backticks to point at it.
questionsobject: Required. Named questions, at least one. Answers come back under the same names.
imagesstring[]: Optional. Base64 photos of the case, read with the text. See Images.
modelstring: Optional. amos-1-large for the hardest calls and amos-1-medium for most decisions, both always on; amos-1-small for quotes, boxes and photos, which sleeps after two idle hours and takes about two minutes to wake. Leave it out, or send anything else, including the SDKs’ default, and amos-1-mini answers.

Question

typestring: One of the six answer types below.
instructionsstring | object | array: The question. Put long reference data in an object and name its fields in backticks.
criteriaobject | array: The options or levels, for the types that take them. Descriptions can be strings, objects, arrays or null.

Request body

{
  "state": {
    "ticket": "Hi, invoice INV-2231 for £306.00 was charged to my card twice this morning. Please refund one of them today.",
    "customer": {
      "plan": "pro",
      "since": "2024-03-02"
    }
  },
  "questions": {
    "refund": {
      "type": "noul",
      "instructions": "Is the customer asking for a refund?"
    },
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoices, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Plans, upgrades, new accounts"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this?",
      "criteria": [
        "Can wait",
        "This week",
        "Today"
      ]
    },
    "mentions": {
      "type": "multi",
      "instructions": "Which details does the ticket mention?",
      "criteria": {
        "invoice number": null,
        "amount": null,
        "bank account": null
      }
    },
    "amount": {
      "type": "span",
      "instructions": "How much was charged?"
    }
  }
}

Answer types

Six types. Mix them freely in one request.

Yes / no response

{ "type": "noul", "noul": 0.986 }

Response

model, answers keyed by your question names, and usage.

type: The question’s type.
noul: Probability the answer is yes, 0 to 1.
choice: The most likely option.
probabilities: Every option or level with its probability. For choice and score they sum to 1. For multi each is its own yes / no.
score: The expected level, weighted by probability. It can fall between levels.
legend: Each level number mapped to its description.
span: An exact phrase from the state.
start, end: Where the span sits in the state, in code points.
box: Where the named thing is in the photo, as [x0, y0, x1, y1], 0 to 1.
cell: The photo patch the model scored highest.
confidence: How settled the answer is, 0 to 1, computed as TypeSafe does. Use it to decide when to act and when to ask a person.

Response

{
  "model": "amos-1-mini",
  "answers": {
    "refund": {
      "type": "noul",
      "noul": 0.992
    },
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.986,
        "technical": 0.007,
        "sales": 0.007
      },
      "confidence": 0.979
    },
    "urgency": {
      "type": "score",
      "score": 1.982,
      "legend": {
        "0": "Can wait",
        "1": "This week",
        "2": "Today"
      },
      "probabilities": {
        "0": 0.002,
        "1": 0.014,
        "2": 0.984
      },
      "confidence": 0.973
    },
    "mentions": {
      "type": "multi",
      "probabilities": {
        "invoice number": 0.973,
        "amount": 0.974,
        "bank account": 0.784
      }
    },
    "amount": {
      "type": "span",
      "span": "£306.00",
      "start": 40,
      "end": 47,
      "confidence": 0.935
    }
  },
  "usage": {
    "input_tokens": 164,
    "output_tokens": 0
  }
}

Models

Four sizes, one API. Name one in model, or leave it out.

amos-1-large128K · 122 ms · 76.1%
amos-1-medium128K · 61 ms · 76.5%
amos-1-small256K · 48 ms · 69.5%
amos-1-mini9K · 27 ms · 64.6%

Context in tokens. Median server time for a three-question request. Typed decisions test accuracy. All scores

Endpoints

POST /v1/systemone: Answer every question about one case.
GET /v1/models: The served model, as { models: [{ name, description, release_date }] }. The SDKs’ models.list() reads it.
GET /v1/info: The model card: parameters, context length, answer types and benchmark scores. Add ?model=NAME for another model, such as ?model=amos-1-mini.

Errors

Errors are JSON with an error message.

413: The body is over 4 MB.
422: The request failed validation, or asks a type this model doesn’t answer. The body names the question and the problem.
429: Over 60 requests a minute from one caller. Retry after the Retry-After header.
500: The server failed to answer. A bug on our side.
503: The queue is full. Retry after the Retry-After header.

422 body

{
  "error": "a region question needs a state image"
}

Rate limits

Over a limit, Amos answers 429 or 503 with Retry-After. The SDKs retry for you.

Requests60 a minute per caller
Concurrent20 at once per caller
Body4 MB
TokensThe model’s context, case and questions together (see Models)
OptionsUp to 255 per choice, pick any or score question
LanguageEnglish

SDKs

Amos speaks the TypeSafe System One API. The official SDKs work unchanged.

Point them at Amos with the variables in the Environment tab, or pass base_url and api_key (Python) or baseURL and apiKey (TypeScript) to the client.

TypeSafe’s own quick start, in the other two tabs, then runs as written.

export TYPESAFE_BASE_URL=https://api.amos.scira.ai
export TYPESAFE_API_KEY=amos        # the SDKs require a key; Amos does not check it
export TYPESAFE_DEFAULT_MODEL=amos-1-mini

Pick any and quote

These types are Amos’s own, so the SDKs have no helpers. Pass plain objects. The Python SDK leaves their answers out of response.answers; read the raw response.

response = client.system_one(
    state="Invoice INV-2231 from Acme Ltd, total £306.00, paid by card.",
    questions={
        "total": {"type": "span", "instructions": "What is the invoice total?"},
        "paid_by": {
            "type": "multi",
            "instructions": "Which payment methods are mentioned?",
            "criteria": {"card": None, "cash": None, "bank transfer": None},
        },
    },
)

# The Python SDK keeps only yes/no, choice and score answers in response.answers.
answers = response.raw_http_response.json()["answers"]
print(answers["total"]["span"])  # £306.00

Compared with other System One APIs

	Amos	TypeSafe Jev	Mercury Decide
Endpoint	api.amos.scira.ai /v1/systemone	api.typesafe.ai /v1/systemone	openrouter.ai /api/alpha/decisions
API key	Any value, not checked	TypeSafe key	OpenRouter key
model	amos-1-mini (default), -small, -medium or -large	jev-latest by default	inception/mercury-decide:free
Answer types	Yes / no, choice, score, pick any, quote, point	Yes / no, choice, score	Yes / no, choice, score
Score levels	Up to 255	Up to 10	Not documented
Photos	Yes	No	No
Queue full	503	529	–
Typed decisions, test	64.6% · KL 0.225	72.7% · KL 1.442	71.5% · KL 0.963

Images

Send photos of the case with the text, as base64 strings.

Put them in images; Amos reads them with the text. region questions need one: they answer with a box around the thing you name.

On RefCOCO photos, Amos 1 small centres a box on the named object 94% of the time, and four boxes in five cover at least half of it. GET /v1/info lists the types the served model answers.

Request with a photo

{
  "model": "amos-1-small",
  "state": "Repair ticket R-5520. The phone slipped off a table. Photo attached.",
  "images": ["<base64 JPEG>"],
  "questions": {
    "cracked": { "type": "noul", "instructions": "Is the screen cracked?" },
    "where": { "type": "region", "instructions": "Where is the crack?" }
  }
}