---
name: secnd
description: Write code that calls the Secnd API (Ren 1.1) for typed decisions. Use when the user wants to send a situation and a choice, score or true/false question to POST /v1/decide, read the returned probability and action, or route uncertain answers to a human.
---

# Secnd API

Ren 1.1 answers one narrow, typed question about a situation and returns a probability for every answer. Your code keeps
control: it defines the answers, honors the `action`, and runs the business logic. Ren does not write conversations.

Docs index for agents: https://docs.secndai.com/llms.txt (every page as Markdown: https://docs.secndai.com/llms-full.txt).
Read the page for the question type you use before writing code.

API access is by request until launch: https://secndai.com/contact. Do not invent keys, prices, dates or scores.

## When to use

- Picking one of a fixed set: queue, category, tool, document class (`choice`).
- Rating against an ordered rubric (`score`).
- Checking one explicit proposition (true/false, wire type `noul`).

Not for free text, arithmetic, or fixed business rules: keep those in code.

## Call POST /v1/decide

Server side only. Read the key from `SECND_API_KEY`; never put it in client code or logs.

```bash
curl --fail-with-body https://api.secndai.com/v1/decide \
  -H "Authorization: Bearer $SECND_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "ren-1.1.0",
    "type": "choice",
    "situation": "A customer says the same order was charged twice.",
    "question": "Which queue should handle this ticket?",
    "options": [
      {"id": "billing", "description": "Payment and invoice problems"},
      {"id": "delivery", "description": "Shipping and parcel problems"}
    ],
    "threshold": 0.9
  }'
```

- `model`: `ren-1.1.0` (pinned), or the aliases `ren-latest` / `ren-preview`. `GET /v1/models` lists what the key can use.
- `choice`: `options` (2–255), each `{id, description}` with unique ids.
- `score`: `levels` (2–10), ids `"1"`..`"10"` strictly increasing, each with a description a reviewer could apply.
- `noul` (true/false): no `options` or `levels`; `question` is one proposition.
- `threshold`: 0–1, default 0.9. Unknown fields are rejected with `422`; input over 2048 tokens gets `413`, never truncated.

## Read the answer

- `choice`: the most probable answer (option id, level id, or `"true"` / `"false"`).
- `probability`: calibrated probability of `choice`, equal to `probabilities[choice]`. For true/false the probability of
  true is `probabilities.true`; for score it is the winning level, and `expected_score` is the probability-weighted level.
- `action`: `"act"` when `probability >= threshold`, else `"ask_human"`. `act` on true/false does not mean true.

## Route low probability to a human

Branch on `action` before any side effect. On `ask_human`, persist a review item (situation, question, options,
suggested answer, probabilities, model, threshold) keyed by your own case id, and require a human decision before any
irreversible step. On `act`, still enforce permissions and business rules. If the call fails (`502`/`503`/`504`/`529`
or a non-JSON body), retry within a bounded budget, then queue review; never make up an answer.

Errors are `{"code", "message"}` JSON with an `X-Request-Id` header; branch on status and `code`. On `429`, honor
`retry-after-ms` or `Retry-After`.

## Docs

- Quickstart: https://docs.secndai.com/quickstart.md
- Question types: https://docs.secndai.com/primitives/index.md
- Probability and the gate: https://docs.secndai.com/confidence.md
- Escalate to a human: https://docs.secndai.com/patterns/escalate-to-human.md
- Errors: https://docs.secndai.com/errors.md
- OpenAPI contract: https://docs.secndai.com/openapi.json