Name: Decide Zero API: Typed Text Decisions and Classification
Brand: cymetica
SKU: api-cymetica-decide-zero
Availability: InStock
Author: API Market

# Decide Zero API

## Overview

Decide Zero answers questions about a text with a typed decision instead of prose. You send a state (the text, or a JSON object) and up to 16 questions, and each question comes back as a choice with a probability for every option, a yes/no probability, or a level on an ordered score. Nothing is trained and nothing is stored: every call is stateless, the model reads the first 480 tokens of the state, and the request body is discarded once the answer is sent. The `/decisions` endpoint takes the native shape, `/chat/completions` wraps the same model in an OpenAI-compatible format, and `/models`, `/health` and `/usage` describe the model, its uptime and the metered usage.

It is built for support and operations teams routing tickets, developers adding guardrails or triage to an app, data teams scoring sentiment or urgency at scale, and AI agent builders who need a machine-readable decision step. Each answer is a small JSON object with the chosen option, the calibrated probabilities and a confidence value you can use as a threshold.

## Features

*   **5 endpoints**: native decisions, an OpenAI-compatible chat endpoint, the model document, service health and usage counts.
*   **Three question types**: `choice` (2 to 255 options), `noul` (a yes/no probability) and `score` (2 to 10 ordered levels).
*   **Calibrated probabilities**: every answer carries the full distribution and a `confidence` value, so you can route confident cases automatically.
*   **Few-shot options**: each option can carry a one-line description and a few example texts; nothing is trained.
*   **Several questions per call**: ask up to 16 questions about the same text in one request.
*   **Zero data retention**: the text is not stored or logged, only usage counts are metered.
*   **Rate limit**: 10 requests per second.

## Use Cases

*   **Support ticket routing**: send each ticket to the right queue by intent, with a probability you can threshold.
*   **Guardrails**: ask yes/no questions such as "is this on topic?" or "does this request personal data?" before a reply goes out.
*   **Sentiment and urgency scoring**: score reviews, emails or chat turns on an ordered scale.
*   **AI agents**: use a typed decision step inside an agent loop instead of parsing free text.
*   **OpenAI client libraries**: plug the model into code that already speaks the chat completions format.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/cymetica/decide-zero
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Answer typed questions about a text

Returns one typed answer per question: for a `choice` question the chosen option, a probability for every option, the confidence and whether the text fits any option.

**Method:** `POST`

**Endpoint:** `/decisions`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `model` | body | Model version: `decide-zero-latest` or `decide-zero-1.1` | string | No | `decide-zero-latest` | - |
| `state` | body | The text to decide about (a string, or a JSON object that is serialised); the model reads its first 480 tokens | string or object | Yes | - | - |
| `questions` | body | Up to 16 questions keyed by your own ids. Each has a `type` (`choice`, `noul` or `score`) plus `criteria` (option ids with one-line descriptions), `question` or levels | object | Yes | - | 16 questions |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/cymetica/decide-zero/decisions' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "decide-zero-latest",
  "state": "I still have not received my new card, I ordered over a week ago.",
  "questions": {
    "intent": {
      "type": "choice",
      "criteria": {
        "card_arrival": "asks when an ordered card will arrive",
        "lost_or_stolen_card": "reports a card lost or stolen",
        "card_not_working": "a card is declined or will not work"
      }
    }
  }
}'
```

**Example Response (200 OK):**

```json
{
  "id": "dec-804368508c814821b022b33bc93ab968",
  "object": "decision",
  "created": 1793657481,
  "model": "decide-zero-1.1",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "card_arrival",
      "probabilities": {
        "card_arrival": 0.990816,
        "lost_or_stolen_card": 0.000457,
        "card_not_working": 0.008727
      },
      "confidence": 0.990816,
      "fits": true
    }
  },
  "usage": {
    "input_tokens": 52,
    "output_tokens": 94
  }
}
```

#### 2. OpenAI-compatible chat completions

Runs the same decision through the chat completions format. Put the questions as JSON in a system message and the text in the last user message (or send a full `{state, questions}` object as the last user message); the answer comes back as JSON in the assistant message.

**Method:** `POST`

**Endpoint:** `/chat/completions`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `model` | body | Model version: `decide-zero-latest` or `decide-zero-1.1` | string | No | `decide-zero-latest` | - |
| `messages` | body | Either the last user message is a Decisions request as JSON (`{state, questions}`), or a system message holds `{questions}` as JSON and the last user message is the state | array of objects | Yes | - | - |
| `stream` | body | Set to `true` to receive the answer as server-sent events | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/cymetica/decide-zero/chat/completions' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "decide-zero-latest",
  "messages": [
    {"role": "system", "content": "{\"questions\": {\"sentiment\": {\"type\": \"noul\", \"question\": \"Is this review positive?\", \"criteria\": {\"true\": \"the writer recommends it\", \"false\": \"the writer is disappointed\"}}}}"},
    {"role": "user", "content": "Arrived late and the box was crushed, but the headphones sound great."}
  ]
}'
```

**Example Response (200 OK):**

```json
{
  "id": "chatcmpl-d704a66dded34c46aa40a023e22398e4",
  "object": "chat.completion",
  "created": 1793657484,
  "model": "decide-zero-1.1",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "{\"answers\": {\"sentiment\": {\"type\": \"noul\", \"noul\": 0.025662, \"confidence\": 0.974338}}}"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 38,
    "total_tokens": 63
  }
}
```

#### 3. Model document

Returns the available model ids with their description, context length, readiness and per-token pricing at the source.

**Method:** `GET`

**Endpoint:** `/models`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/decide-zero/models' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "schema_version": "2.4",
  "data": [
    {
      "schema_version": "2.4",
      "id": "decide-zero-1.1",
      "name": "Decide Zero 1.1",
      "created": 1790553600,
      "description": "Decide Zero answers typed questions about a text: choice (2-255 options), noul (a yes/no probability) and score (2-10 ordered levels), with calibrated probabilities and no prose...",
      "input_modalities": [
        {
          "type": "text",
          "supported_inputs": {
            "max_context_length": {"value": 32768},
            "max_prompt_length": {"value": 32768}
          }
        }
      ],
      "is_ready": true,
      "quantization": "fp32",
      "tokenizer": "BERT"
    }
  ]
}
```

#### 4. Service health

Returns whether the model is being served and its measured uptime today and over the last 7 days.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/decide-zero/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "model": "decide-zero-1.1",
  "served": true,
  "zero_data_retention": true,
  "uptime_today": {"requests": 270, "answered": 270, "uptime": 1.0},
  "uptime_7d": {"requests": 1997, "answered": 1997, "uptime": 1.0}
}
```

#### 5. Usage counts

Returns requests and tokens per day as metered at the source.

**Method:** `GET`

**Endpoint:** `/usage`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `days` | query | Number of past days to include | integer | No | `30` | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/cymetica/decide-zero/usage?days=7' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "key": "apimarket",
  "days": [
    {"day": "20261102", "requests": 2, "input_tokens": 77, "output_tokens": 132}
  ],
  "metering": "available"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The decision, model document, health or usage was returned. |
| 400 | Bad Request | The body is not valid JSON, or `state` or `questions` is missing or malformed. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is invalid. |
| 403 | Forbidden | Your key has no active subscription to Decide Zero. Enable the pay-as-you-go plan. |
| 404 | Not Found | The endpoint path is wrong. Check it against the list above. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Wait and retry. |
| 500 | Internal Server Error | The model failed to answer. Retry the request. |
| 503 | Service Unavailable | The model is temporarily not served. Check `/health` and retry later. |

## Rate Limits

The pay-as-you-go plan allows 10 requests per second. Requests above that return 429; throttle your client, back off and retry, and honour the `Retry-After` header when it is present. Ask several questions about the same text in one request instead of one call per question.

## FAQ

*   **What is a `noul` question?**

    A yes/no question answered as a probability (0 to 1) that the statement holds for the text, with a `confidence` value.

*   **Do I need training data?**

    No. Describe each option in one line and optionally add a few example texts; nothing is trained or kept.

*   **How long can the text be?**

    The model reads the first 480 tokens of the state, so long documents should be trimmed to the part that matters.

*   **How is it billed?**

    Pay as you go, by the size of each request, so short texts cost less than long ones.

*   **When should I use `/chat/completions` instead of `/decisions`?**

    Use it when your code already uses an OpenAI client library. The answer is the same JSON, returned in the assistant message.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Typed decisions with calibrated probabilities: choice, yes/no, score. Send examples per option; nothing is trained or kept.