Quickstart

Make your first typed decision in a few minutes. This quickstart calls a Modaic base model directly, so you do not need to create a model repository first.

1. Create an API key

Create a key in the Modaic dashboard, then store it in an environment variable.

export MODAIC_API_KEY="mdc_..."

The key needs the write:repository scope to create decisions.

2. Ask typed questions

Send any JSON value as state. Each key in questions becomes a key in the response's answers object.

curl --request POST \
  --url 'https://api.modaic.dev/v1/decision' \
  --header "Authorization: Bearer $MODAIC_API_KEY" \
  --header "Idempotency-Key: quickstart-$(date +%s)" \
  --header 'Content-Type: application/json' \
  --data '{
    "state": {
      "ticket": "I was charged twice for order 4832. Please refund one charge."
    },
    "model": "mo",
    "questions": {
      "needs_refund": {
        "type": "noul",
        "instructions": "Should this customer receive a refund?",
        "criteria": {
          "true": "A duplicate or invalid charge should be refunded.",
          "false": "The charge is valid or more information is required."
        }
      },
      "priority": {
        "type": "choice",
        "instructions": "Choose the support priority.",
        "criteria": {
          "low": "No financial or time-sensitive impact.",
          "normal": "Routine customer issue.",
          "high": "Financial impact or an urgent blocker."
        }
      }
    }
  }'

Modaic returns one typed answer per question and reports token usage.

{
  "model": "mo",
  "answers": {
    "needs_refund": {
      "type": "noul",
      "noul": 0.97
    },
    "priority": {
      "type": "choice",
      "choice": "high",
      "probabilities": {
        "low": 0.01,
        "normal": 0.05,
        "high": 0.94
      },
      "confidence": 0.94
    }
  },
  "usage": {
    "input_tokens": 186,
    "output_tokens": 42
  }
}

3. Make it versioned

Create a model repository when you want to capture production examples, annotate decisions, run alignment, and pin exact revisions. Then call the same endpoint with a model path such as acme/support-triage instead of mo.

Next steps

Decision API — all question types, capture controls, and response fields.
Create a model — create a private, versioned model repository.
Ingest examples — add a dataset and optional ground truth.
Start an alignment — improve instructions from annotated examples.

Was this page helpful?