Quickstart

Sign up, create an API key in the console, send your first decision run to OpenType, and read the probabilities it returns. About five minutes.

This page takes you from no account to a completed decision run: one request that asks three typed questions about a support ticket and returns a probability for every answer. It is for developers making their first call. You need a terminal with curl, or Node.js 18+ or Python 3 with requests.

1. Create an account

   Sign up at console.opentype.dev/sign-up and verify your email address. Verifying gives your new organization $5 of free credit (5,000,000 micro-USD), once per email address. At the cost of the run below, that covers more than 250,000 runs.

   The details, including the sign-in options, are on Create an account.

2. Create an API key

   In the console, open API keys and choose + Create key.

   1. Give the key a Name after the process that will hold it, for example Production ticket router. The name is a label, not a credential.
   2. Under Scopes, keep Send requests. It grants runs_write (send runs) and runs_read (read them back), which is all this page needs.
   3. Choose + Create key and show secret.
   4. Choose Copy secret, store it somewhere safe, then choose I have copied it.

   

   The secret is otsk_ followed by 64 lowercase hex characters. It is shown once. Only a SHA-256 hash of it is stored, so a lost secret cannot be recovered: revoke the key and create another. See API keys.

3. Export the key

   Keep the key in an environment variable, never in source code.

   export OPENTYPE_API_KEY="otsk_..."
   

   Every example on this site reads the key from OPENTYPE_API_KEY.

4. Send a decision run

   This run triages a support ticket with three questions: a yes/no (noul), a one-of-N (choice), and an ordered level (score).

   cURL

   curl -sS https://api.opentype.dev/v1/runs \
     -H "Authorization: Bearer $OPENTYPE_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: ticket-4822-triage" \
     -d '{
       "kind": "decision",
       "instructions": "You triage customer support tickets.",
       "state": {"ticket": "I was charged twice this month and nobody answers my emails.", "plan": "pro"},
       "questions": {
         "urgent": {"type": "noul", "instructions": "reply within the hour?"},
         "bucket": {"type": "choice", "instructions": "which queue?",
                    "criteria": {"billing": "payment problems", "other": null}},
         "tone":   {"type": "score", "instructions": "how annoyed?",
                    "criteria": ["calm", "annoyed", "furious"]}
       },
       "question_order": ["urgent", "bucket", "tone"],
       "think_tokens": 64,
       "max_output_tokens": 16
     }'
   

   The request is synchronous: it returns 200 once the run has finished. kind: "decision" is required here, because a request without kind is treated as a verdict run. think_tokens: 64 lets the model reason for up to 64 hidden tokens before it answers; the reasoning text is never returned.

5. Read the answers

   {
     "run_id": "run_a4314b6cc08f4bd8814099a613abeb44",
     "kind": "decision",
     "state": "completed",
     "input_digest": "2e7d2c03a9507ae265ecf5b5356885a53393a2029d241394997265a1a25aefc6",
     "output_digest": "18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4",
     "decision": {
       "answers": {
         "bucket": {"answered_within_labels": true, "choice": "billing", "confidence": 0.71,
                    "label_mass": 0.964, "probabilities": {"billing": 0.71, "other": 0.29}, "type": "choice"},
         "tone":   {"answered_within_labels": true, "confidence": 0.46, "label_mass": 0.98,
                    "legend": {"0": "calm", "1": "annoyed", "2": "furious"},
                    "probabilities": {"0": 0.12, "1": 0.42, "2": 0.46}, "score": 1.34, "type": "score"},
         "urgent": {"answered_within_labels": true, "label_mass": 0.991, "probability": 0.83, "type": "noul"}
       },
       "draws": 1,
       "read": "slot_constrained",
       "model": "neon-1.1",
       "stages": [["urgent", "bucket", "tone"]],
       "thought_tokens": 48,
       "thought_closed": true
     },
     "usage": {"input_tokens": 412, "output_tokens": 23},
     "cost_micros": 19,
     "cost_basis": "provider_reported",
     "replayed": false
   }
   

   Answer	How to read it
   urgent.probability: 0.83	A noul answer is P(yes): the model puts 83% on “yes”. There is no confidence on a noul.
   bucket.choice: "billing"	The most likely option. probabilities has every option you defined, keyed by option name. The answer also carries a confidence.
   tone.score: 1.34	A score is the expected level, 0-indexed on your list. legend maps each index to your level name, so 1.34 sits between annoyed (1) and furious (2). probabilities is keyed by index.
   label_mass, answered_within_labels	How much of the model’s probability landed on your labels. When answered_within_labels is false, the probabilities are a renormalization over labels the model did not favour, so do not treat them as calibrated.
   cost_micros: 19	What the run cost, in micro-USD: $0.000019. 412 input tokens round up to 18 micros and 23 output tokens to 1. See Models and pricing.
   replayed: false	This response came from a new model call, not from storage.

   answers keys are always sorted, whatever order you sent. stages shows the order the questions were read in, and thought_tokens how many of the 64 thinking tokens the model used.

6. Read the run back

   Every run is stored under its run_id. Fetch it with the same key; it needs runs_read.

   cURL

   curl -sS https://api.opentype.dev/v1/runs/run_a4314b6cc08f4bd8814099a613abeb44 \
     -H "Authorization: Bearer $OPENTYPE_API_KEY"
   

   The stored run carries the same answers, usage and cost_micros, with replayed: true. It is thinner than the live response: it has no cost_basis, and its decision has no model or stages. See Runs.

Retry safely

Send the same request again with the same Idempotency-Key and you get the stored run back with replayed: true. There is no second model call and no second charge. Reusing a key with a different body is refused with 409 idempotency_conflict.

If a run fails with a 503 or 504 before any model served it, send the retry with a new key: the first key stays attached to a pending run, and replaying it answers 202 with that run. The Idempotency guide covers every case.

What goes wrong

Status and code	Cause	Fix
401 missing_credentials	No Authorization: Bearer header, or OPENTYPE_API_KEY is empty in this shell.	Run echo $OPENTYPE_API_KEY and export it again.
401 invalid_credential	The key is mistyped, truncated, or revoked.	Copy the whole 69-character secret, or create a new key.
403 scope_denied	The key lacks runs_write (to send) or runs_read (to read back).	Create a key with the Send requests scope set.
400 idempotency_key_required	No Idempotency-Key header on POST /v1/runs.	Send one, 1 to 255 bytes.
400 invalid_body	Invalid JSON, a missing Content-Type: application/json, an unknown field, or no max_output_tokens.	Read error.message; it names the problem.
400 invalid_decision_questions	The question set breaks a bound, for example a choice with one option.	See the bounds on Decision questions.
402 insufficient_credits	Your available balance is below the $0.02 a run holds while it is in flight.	Verify your email to receive the free credit, or buy credits.
413 input_too_large	The state and questions do not fit the 262,144-token context of Neon 1.1.	Send a smaller state.
503 decision_unavailable	The question set could not be read, or no route could serve it now.	Retry later with a new Idempotency-Key.

Every error body has the same shape. Branch on code, and log request_id:

{"error": {"code": "scope_denied", "message": "the session lacks the runs_write scope", "request_id": "req_7d3f0c1a9b2e4f6a8c0d1e2f3a4b5c6d"}}

More causes and fixes are on Troubleshooting and Errors.

Related

• Decision questions - add dependencies, conditional questions, and more options.
• Decision runs - turn probabilities into thresholds for a real triage flow.
• API keys - create, rotate, and revoke keys in the console.
• Scopes and roles - which scopes a production key should hold.
• Limits - every size, token, and spend bound in one table.