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.

The inference API is in development and is not yet available. The endpoint, examples, limits, and SDK compatibility below describe a proposed contract, not a working service. Follow development.

Request example

This illustrates the proposed request shape. No API base URL or keys are currently issued.

curl "$NEEDLE_API_BASE_URL/v1/decisions" \
  -H "Authorization: Bearer $NEEDLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "needle-1.0",
    "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"]
      }
    }
  }'

In the proposed contract, state accepts text or a JSON value. Question IDs are returned as answer keys rather than 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.

Illustrative response

These are fixed example values, not a response from a hosted service.

{
  "model": "needle-1.0",
  "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}
}

The proposed usage object reports input tokens and zero output tokens. Input-token accounting has not been implemented as a public service.

Proposed limits

These are design targets, not enforced service limits or a throughput commitment.

• 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

Proposed 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 status

No Needle SDK or third-party SDK compatibility is currently offered. Client integrations will need validation against an implemented service.