Needle API

Needle answers typed questions about a piece of state. One request carries the state and a map of questions. One forward pass answers all of them. The model never generates text.

Needle is in private preview. The endpoint below accepts keys issued from the preview list.

Quickstart

curl https://api.gaugenumerics.com/v1/decisions \
  -H "Authorization: Bearer $NEEDLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "needle-1",
    "state": "Customer was charged twice for order 4417.",
    "questions": {
      "action": {
        "type": "choice",
        "instructions": "Should the duplicate charge be refunded?",
        "criteria": {"refund": null, "deny": null}
      },
      "urgent": {"type": "noul", "instructions": "Is this urgent?"},
      "severity": {
        "type": "score",
        "instructions": "Rate the severity.",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'

state is text or any JSON value. Question IDs are yours: they come back as the answer keys and are never shown to the model.

Primitives

Choice

criteria is a map from option to an optional description. Returns the chosen option, a probability per option, and a confidence.

Score

criteria is an ordered list of 2 to 10 levels. Returns a fractional score: the probability-weighted level index. It is not rounded to a level.

Noul

A yes/no question. Returns noul, the probability that the answer is true. Optional criteria describe what true and false mean.

Response

{
  "model": "needle-1",
  "answers": {
    "action": {
      "type": "choice",
      "choice": "refund",
      "probabilities": {"refund": 0.97, "deny": 0.03},
      "confidence": 0.94
    },
    "urgent": {"type": "noul", "noul": 0.22},
    "severity": {
      "type": "score",
      "score": 0.61,
      "probabilities": {"0": 0.48, "1": 0.43, "2": 0.09},
      "legend": {"0": "low", "1": "medium", "2": "high"},
      "confidence": 0.22
    }
  },
  "usage": {"input_tokens": 212, "output_tokens": 0}
}

usage.output_tokens is always 0.

Limits

• 256 questions per request
• 255 options per Choice, 2 to 10 levels per Score
• 65,536 characters of state, 2,048 characters of instructions
• 2 MiB request body

Errors

• 401 missing or invalid API key
• 413 request body too large
• 422 malformed request or a limit exceeded
• 429 rate limited, retry with backoff
• 503 inference unavailable, retry with backoff

SDK compatibility

The request and response shapes match the System One contract, so the typesafe-sdk Python client works by pointing its base_url at Needle.