{
 "openapi": "3.0.3",
 "info": {
  "title": "Decide Zero",
  "version": "1.1",
  "description": "Typed decisions about a text with calibrated probabilities and no prose: choice (2-255 options), noul (a yes/no probability) and score (2-10 ordered levels). Send a state (the text) and questions; each choice option can carry a one-line description and a few example texts. Nothing is trained and nothing is kept (zero data retention). Benchmarks: with one example per option, 82.11% on BANKING77 (3 per option 85.13%, 5 per option 85.71%) at a calibration error of 0.017; zero-shot (names and descriptions only) 77.18%, so send examples. Evidence and scorer: https://cymetica.com/static/research/decide-zero/ . Typical answer time 170 ms (p95 240 ms).",
  "contact": {
   "name": "Cymetica",
   "url": "https://cymetica.com",
   "email": "contact@cymetica.com"
  },
  "termsOfService": "https://cymetica.com/terms",
  "license": {
   "name": "Proprietary"
  }
 },
 "servers": [
  {
   "url": "https://cymetica.com/api/v1/decide/zero/v1",
   "description": "Production (Japan)"
  }
 ],
 "security": [
  {
   "bearer": []
  },
  {
   "apiKey": []
  }
 ],
 "tags": [
  {
   "name": "Decide",
   "description": "Answer typed questions about a text"
  },
  {
   "name": "Account",
   "description": "Usage and service status"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Authorization: Bearer <key>"
   },
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Api-Key"
   }
  },
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "RateLimited": {
    "description": "More than the key's requests a minute (600 by default) or the service at capacity; retry after the Retry-After seconds",
    "headers": {
     "Retry-After": {
      "schema": {
       "type": "integer"
      }
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  },
  "schemas": {
   "ChoiceQuestion": {
    "type": "object",
    "required": [
     "type"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "choice"
      ]
     },
     "options": {
      "type": "array",
      "items": {
       "type": "string",
       "maxLength": 255
      },
      "minItems": 2,
      "maxItems": 255,
      "description": "Option names (or give `criteria` instead)"
     },
     "criteria": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "{option: one-line description}. The keys are the options."
     },
     "examples": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "description": "{option: [example texts]}. One to five examples per option lifts BANKING77 accuracy from 77% (none) to 82-86%."
     },
     "allow_unclear": {
      "type": "boolean",
      "default": false,
      "description": "Let the model abstain with `unclear`"
     }
    }
   },
   "NoulQuestion": {
    "type": "object",
    "required": [
     "type"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "noul"
      ]
     },
     "question": {
      "type": "string",
      "description": "A yes/no question about the state, e.g. \"Is this review positive?\""
     },
     "criteria": {
      "type": "object",
      "properties": {
       "true": {
        "type": "string"
       },
       "false": {
        "type": "string"
       }
      },
      "description": "What makes the answer true / false (raises accuracy from 51% to 85-91% on reviews)"
     }
    }
   },
   "ScoreQuestion": {
    "type": "object",
    "required": [
     "type",
     "levels"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "score"
      ]
     },
     "question": {
      "type": "string"
     },
     "levels": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "minItems": 2,
      "maxItems": 10,
      "description": "Ordered levels, lowest first, e.g. [\"1 star\", ..., \"5 stars\"]"
     }
    }
   },
   "Question": {
    "oneOf": [
     {
      "$ref": "#/components/schemas/ChoiceQuestion"
     },
     {
      "$ref": "#/components/schemas/NoulQuestion"
     },
     {
      "$ref": "#/components/schemas/ScoreQuestion"
     }
    ]
   },
   "DecisionsRequest": {
    "type": "object",
    "required": [
     "state",
     "questions"
    ],
    "properties": {
     "model": {
      "type": "string",
      "enum": [
       "decide-zero-1.1",
       "decide-zero-latest"
      ],
      "default": "decide-zero-latest"
     },
     "state": {
      "description": "The text to decide about (a string, or a JSON object that is serialised); the model reads its first 480 tokens",
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "object"
       }
      ]
     },
     "questions": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/Question"
      },
      "description": "Up to 16 questions keyed by your own ids"
     }
    }
   },
   "Answer": {
    "type": "object",
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "choice",
       "noul",
       "score"
      ]
     },
     "choice": {
      "type": "string",
      "description": "choice: the chosen option"
     },
     "probabilities": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      },
      "description": "choice / score: every option's or level's probability"
     },
     "confidence": {
      "type": "number",
      "description": "the chosen option's probability"
     },
     "p_true": {
      "type": "number",
      "description": "noul: probability the answer is yes"
     },
     "level": {
      "type": "string",
      "description": "score: the answered level"
     },
     "expected_position": {
      "type": "number",
      "description": "score: probability-weighted position, 1 = lowest level"
     },
     "fits": {
      "type": "boolean",
      "description": "whether the state fits the question at all"
     }
    }
   },
   "DecisionsResponse": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string",
      "enum": [
       "decision"
      ]
     },
     "created": {
      "type": "integer"
     },
     "model": {
      "type": "string"
     },
     "answers": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/Answer"
      }
     },
     "usage": {
      "$ref": "#/components/schemas/Usage"
     }
    }
   },
   "Usage": {
    "type": "object",
    "properties": {
     "input_tokens": {
      "type": "integer"
     },
     "output_tokens": {
      "type": "integer"
     }
    }
   },
   "ChatMessage": {
    "type": "object",
    "required": [
     "role",
     "content"
    ],
    "properties": {
     "role": {
      "type": "string",
      "enum": [
       "system",
       "developer",
       "user",
       "assistant"
      ]
     },
     "content": {
      "type": "string"
     }
    }
   },
   "ChatRequest": {
    "type": "object",
    "required": [
     "messages"
    ],
    "properties": {
     "model": {
      "type": "string",
      "enum": [
       "decide-zero-1.1",
       "decide-zero-latest"
      ],
      "default": "decide-zero-latest"
     },
     "messages": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ChatMessage"
      },
      "description": "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"
     },
     "stream": {
      "type": "boolean",
      "default": false
     }
    }
   },
   "ChatCompletion": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "object": {
      "type": "string",
      "enum": [
       "chat.completion"
      ]
     },
     "created": {
      "type": "integer"
     },
     "model": {
      "type": "string"
     },
     "choices": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "index": {
         "type": "integer"
        },
        "finish_reason": {
         "type": "string"
        },
        "message": {
         "type": "object",
         "properties": {
          "role": {
           "type": "string"
          },
          "content": {
           "type": "string",
           "description": "JSON text: {\"answers\": {...}}"
          }
         }
        }
       }
      }
     },
     "usage": {
      "type": "object",
      "properties": {
       "prompt_tokens": {
        "type": "integer"
       },
       "completion_tokens": {
        "type": "integer"
       },
       "total_tokens": {
        "type": "integer"
       }
      }
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "question": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 },
 "paths": {
  "/decisions": {
   "post": {
    "tags": [
     "Decide"
    ],
    "operationId": "decisions",
    "summary": "Answer typed questions about a text",
    "description": "The native request: a state and up to 16 questions. Each answer carries the chosen option or level, every option's probability and a calibrated confidence. Give each choice option a one-line description and one to five example texts for the best accuracy.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/DecisionsRequest"
       },
       "example": {
        "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"
          },
          "examples": {
           "card_arrival": [
            "How long until my card gets here?"
           ],
           "lost_or_stolen_card": [
            "Someone stole my wallet with my card in it"
           ],
           "card_not_working": [
            "My card keeps getting declined at the shop"
           ]
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The answers",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/DecisionsResponse"
        },
        "example": {
         "id": "dec-1a2b",
         "object": "decision",
         "created": 1761955200,
         "model": "decide-zero-1.1",
         "answers": {
          "intent": {
           "type": "choice",
           "choice": "card_arrival",
           "confidence": 0.977,
           "probabilities": {
            "card_arrival": 0.977,
            "lost_or_stolen_card": 0.015,
            "card_not_working": 0.008
           },
           "fits": true
          }
         },
         "usage": {
          "input_tokens": 96,
          "output_tokens": 24
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "404": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     },
     "503": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/chat/completions": {
   "post": {
    "tags": [
     "Decide"
    ],
    "operationId": "chatCompletions",
    "summary": "OpenAI-compatible: the last user message is a Decisions request",
    "description": "Drop-in for OpenAI-style clients and model routers. The assistant message is the JSON text {\"answers\": {...}}. Streaming (`stream: true`) sends the answers as one chunk followed by usage.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChatRequest"
       },
       "example": {
        "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 themselves are superb."
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Chat completion whose message holds the answers",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ChatCompletion"
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     },
     "503": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/models": {
   "get": {
    "tags": [
     "Account"
    ],
    "operationId": "models",
    "summary": "The model document (public)",
    "security": [],
    "responses": {
     "200": {
      "description": "Provider model document: ids, pricing, context, datacenter, is_ready",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/health": {
   "get": {
    "tags": [
     "Account"
    ],
    "operationId": "health",
    "summary": "Served or not, measured uptime today and over 7 days (public)",
    "security": [],
    "responses": {
     "200": {
      "description": "Health",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "model": {
           "type": "string"
          },
          "served": {
           "type": "boolean"
          },
          "zero_data_retention": {
           "type": "boolean"
          },
          "uptime_today": {
           "type": "object"
          },
          "uptime_7d": {
           "type": "object"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/usage": {
   "get": {
    "tags": [
     "Account"
    ],
    "operationId": "usage",
    "summary": "Requests and tokens used by this key",
    "parameters": [
     {
      "name": "days",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 30,
       "minimum": 1,
       "maximum": 90
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Usage by day",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 }
}