Decisions API documentation and integration guide

Quickstart

Make a decision request end to end

The Playground is the fastest way to understand Decisions API’s inputs and outputs. Once the question is useful, create an API key and connect it to your product.

1. 1

   landing.docs.quickstart.one.title

   Open the playground and load a support, operations, or policy scenario that resembles your application.

2. 2

   landing.docs.quickstart.two.title

   Provide only the fields needed for the decision. Use text for a short message or JSON when account and policy context matter.

3. 3

   landing.docs.quickstart.three.title

   Give each question an ID and choose Choice, Score, or Noul. Each question is evaluated against the same state.

4. 4

   landing.docs.quickstart.four.title

   Create an API key and send the request from your server. Validate the response before using it to trigger an application action.

Input

Shape the state around the decision

A state is shared context for the questions in a request. Keep it relevant: include the event, records, and policy facts needed for the judgment, and omit unrelated personal or account data.

Current input boundary: Decisions API accepts text, JSON objects, and arrays of text. Image, audio, and video inputs are not supported yet.

Question types

Define outcomes your code can handle

Each question should represent one decision your application needs. Use Choice for a finite set of actions, Score for an ordered rubric, or Noul for a binary check; separate questions can share one state.

{
  "type": "noul",
  "instructions": "Does this message convey urgency?",
  "criteria": {
    "true": "Explicitly needs immediate attention",
    "false": "No urgency expressed"
  }
}

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

{
  "state": "A rollout of release 4.8.1 is producing elevated checkout errors in us-east-1. The error budget is nearly exhausted.",
  "model": "jev-latest",
  "questions": {
    "rollout_action": {
      "type": "choice",
      "instructions": "What should the on-call team do next?",
      "criteria": {
        "pause_rollout": "Stop additional traffic",
        "rollback": "Return to the previous version",
        "monitor": "Continue while watching metrics"
      }
    }
  }
}

{
  "state": "A rollout of release 4.8.1 is producing elevated checkout errors in us-east-1. The error budget is nearly exhausted.",
  "model": "jev-latest",
  "questions": {
    "impact": {
      "type": "score",
      "instructions": "How severe is the customer impact?",
      "criteria": [
        "Limited",
        "Elevated",
        "Critical"
      ]
    }
  }
}

{
  "state": "A rollout of release 4.8.1 is producing elevated checkout errors in us-east-1. The error budget is nearly exhausted.",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "Should the rollout be paused and escalated for review?",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}

Output

Validate the answer before acting

Match each response entry to its question ID and expected type. Probabilities and confidence help route uncertain cases, but they are not guarantees; use your own thresholds and review rules.

• answers: Choice returns the selected choice, probabilities, and confidence; Score returns score, legend, per-level probabilities, and confidence; Noul returns noul.
• usage: Includes input_tokens and output_tokens, and may include cost in USD.
• elapsedMs: Time from sending the request to receiving the result, including validation—not pure model inference time.

Probability and confidence are signals for automation, not a guarantee of business accuracy. Use higher thresholds or human review for high-risk actions.

{
  "model": "jev-1.13.0",
  "answers": {
    "pause_rollout": {
      "type": "noul",
      "noul": 0.91
    }
  },
  "usage": {
    "input_tokens": 183,
    "output_tokens": 24
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "rollout_action": {
      "type": "choice",
      "choice": "pause_rollout",
      "probabilities": {
        "pause_rollout": 0.91,
        "rollback": 0.07,
        "monitor": 0.02
      },
      "confidence": 0.84
    }
  },
  "usage": {
    "input_tokens": 221,
    "output_tokens": 31
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "impact": {
      "type": "score",
      "score": 1.16,
      "legend": {
        "0": "Limited",
        "1": "Elevated",
        "2": "Critical"
      },
      "probabilities": {
        "0": 0.02,
        "1": 0.8,
        "2": 0.18
      },
      "confidence": 0.79
    }
  },
  "usage": {
    "input_tokens": 214,
    "output_tokens": 28
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "pause_rollout": {
      "type": "noul",
      "noul": 0.91
    }
  },
  "usage": {
    "input_tokens": 183,
    "output_tokens": 24
  }
}

API reference

Send a server-side request

Call the Decisions API System One endpoint from your backend with a bearer API key. Keep credentials out of browser code, validate inputs, and handle non-success HTTP responses before connecting results to production actions.

Authorization: Bearer <API_KEY>
Content-Type: application/json

curl -X POST https://decisions-api.pro/v1/systemone \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "A rollout of release 4.8.1 is producing elevated checkout errors in us-east-1. The error budget is nearly exhausted.",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "Should the rollout be paused and escalated for review?",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}'

{
  "state": "A rollout of release 4.8.1 is producing elevated checkout errors in us-east-1. The error budget is nearly exhausted.",
  "model": "jev-latest",
  "questions": {
    "pause_rollout": {
      "type": "noul",
      "instructions": "Should the rollout be paused and escalated for review?",
      "criteria": {
        "true": "The release is causing material customer impact and should stop",
        "false": "Evidence does not support stopping the rollout"
      }
    }
  }
}

Keep your API key in a server-side environment variable. Never put it in browser code or commit it to your repository. This page includes the request fields, question types, response shape, error codes, and retry behavior.

Agent usage

Use Decisions API inside a coding agent

Use the Decisions API endpoint from compatible coding agents for bounded decisions while keeping execution and permissions in your application.

export DECISIONS_API_KEY="sk_your_key_here"
export DECISIONS_API_BASE_URL="https://decisions-api.pro"

Classify this support ticket into exactly one team: billing, technical, account, or sales. Return the selected team, probabilities, and confidence. Do not contact the customer or modify any ticket yet.

Ticket: I was charged twice for my annual plan and need a refund.

Before running this proposed tool call, call your Decisions API integration to assess the decision. Judge whether it is safe without human approval. Consider side effects, reversibility, scope, and policy. If risky or uncertain, do not execute it.

Tool: delete_customer_records
Arguments: {where: last_login < 2023-01-01}
Policy: destructive database operations require a backup and human approval.

Use Decisions API to choose one approved model for this task. Optimize for quality first, then context capacity and cost. Return the selected model, probabilities, and whether to escalate. Do not call any model yet.

Task: review a 100k-token customer dispute.
Candidates: fast-model (32k, low cost), reasoning-model (200k, high cost), fallback-model (128k, medium cost).

Use Decisions API to check whether the evidence is sufficient to publish this claim. Consider source quality, freshness, direct support, and contradictions. Return a yes probability and the missing verification work. Do not publish yet.

Claim: Our API reduced median processing time by 40%.
Evidence: an internal benchmark from last month with 120 cases; no production traffic data; an older report showing a 12% improvement.

Use Decisions API to review whether this task is complete. Return one of complete, verify_more, or incomplete. Consider the objective, files changed, tests run, known gaps, and target-environment verification.

Objective: add API-key authentication to the production endpoint.
Completed: added the Authorization check and API-key lookup.
Verification: unit tests pass; production request and rate-limit behavior were not tested.

Error handling

Errors and retries

Handle invalid requests as client errors, missing or invalid credentials as authorization failures, and rate limits or temporary overload with bounded exponential backoff.

When you receive a 429 or 529, retry with exponential backoff instead of sending the same request immediately. SDKs with their default retry policy can handle these retries automatically.