{
  "openapi": "3.1.0",
  "info": {
    "title": "Shvydko Public API",
    "version": "1.0.0",
    "description": "Typed decisions using Choice, Score and Noul. Operated by Codebridge Technology, Inc. The document version describes this API contract, not a pinned model version. Read /api/config for current mode and gateway limits. POST requests are not guaranteed idempotent; a client timeout does not prove the request was not processed.",
    "termsOfService": "https://shvydko.ai/terms"
  },
  "servers": [
    {
      "url": "https://shvydko.ai"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "Read the current public model card",
        "description": "Requires an API key. Context metadata is optional; do not infer inference quality or availability from a successful metadata response.",
        "responses": {
          "200": {
            "description": "Public model metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Model unavailable, timed out or returned an invalid response; no credits charged for this failed request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Model service is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/systemone": {
      "post": {
        "operationId": "evaluateDecision",
        "summary": "Evaluate typed questions over shared state",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionRequest"
              },
              "example": {
                "state": "Card checkout is unavailable; cash on delivery works.",
                "questions": {
                  "team": {
                    "type": "choice",
                    "instructions": "Select the primary support team.",
                    "criteria": {
                      "engineering": "Website or payment integration failure",
                      "logistics": "Shipment or delivery issue",
                      "review": "Insufficient evidence"
                    }
                  },
                  "has_alternative": {
                    "type": "noul",
                    "instructions": "Is another payment method available?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated decisions and actual request accounting",
            "headers": {
              "x-shvydko-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "Matches request_id in the response."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DecisionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Paid mode only: available credits cannot cover the token reservation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Organization requests paused pending billing review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Request reservation expired; inspect Usage before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds the configured JSON byte limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Invalid body, unknown model or context rejected by the model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or daily preview quota reached; Retry-After may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait when provided. Daily preview quota errors may omit this header.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "502": {
            "description": "Model unavailable, timed out or returned an invalid response; no credits charged for this failed request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Model service is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Create an API key in the Shvydko console; keep it in your server environment."
      }
    },
    "schemas": {
      "DecisionRequest": {
        "additionalProperties": false,
        "properties": {
          "state": {
            "title": "State",
            "description": "Facts shared by every question; any JSON value."
          },
          "questions": {
            "additionalProperties": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ChoiceQuestion"
                },
                {
                  "$ref": "#/components/schemas/ScoreQuestion"
                },
                {
                  "$ref": "#/components/schemas/NoulQuestion"
                }
              ]
            },
            "maxProperties": 32,
            "minProperties": 1,
            "title": "Questions",
            "type": "object",
            "propertyNames": {
              "minLength": 1,
              "maxLength": 100
            }
          },
          "model": {
            "anyOf": [
              {
                "maxLength": 100,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model",
            "description": "Optional public model name from GET /v1/models. Omit to use the configured model."
          }
        },
        "required": [
          "state",
          "questions"
        ],
        "title": "DecisionRequest",
        "type": "object"
      },
      "ChoiceQuestion": {
        "type": "object",
        "properties": {
          "type": {
            "const": "choice"
          },
          "instructions": {},
          "criteria": {
            "type": "object",
            "minProperties": 1,
            "maxProperties": 255,
            "additionalProperties": {}
          }
        },
        "required": [
          "type",
          "criteria"
        ],
        "additionalProperties": false
      },
      "ScoreQuestion": {
        "type": "object",
        "properties": {
          "type": {
            "const": "score"
          },
          "instructions": {},
          "criteria": {
            "type": "array",
            "minItems": 1,
            "maxItems": 255,
            "items": {}
          }
        },
        "required": [
          "type",
          "criteria"
        ],
        "additionalProperties": false
      },
      "NoulQuestion": {
        "type": "object",
        "properties": {
          "type": {
            "const": "noul"
          },
          "instructions": {},
          "criteria": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "true": {},
                  "false": {}
                },
                "required": [],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false
      },
      "ChoiceAnswer": {
        "type": "object",
        "properties": {
          "type": {
            "const": "choice"
          },
          "choice": {
            "type": "string"
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "description": "One entry per supplied option; sums to one within numerical tolerance."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "type",
          "choice",
          "probabilities",
          "confidence"
        ],
        "additionalProperties": false
      },
      "ScoreAnswer": {
        "type": "object",
        "properties": {
          "type": {
            "const": "score"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "description": "Expected zero-based level; may be fractional. Maximum is the number of supplied levels minus one."
          },
          "probabilities": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "description": "One entry per supplied option; sums to one within numerical tolerance."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "legend": {
            "type": "object",
            "additionalProperties": {}
          }
        },
        "required": [
          "type",
          "score",
          "probabilities",
          "confidence",
          "legend"
        ],
        "additionalProperties": false
      },
      "NoulAnswer": {
        "type": "object",
        "properties": {
          "type": {
            "const": "noul"
          },
          "noul": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "type",
          "noul"
        ],
        "additionalProperties": false
      },
      "Usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "cost_microusd": {
            "type": "integer",
            "minimum": 0
          },
          "cost_usd": {
            "type": "string",
            "description": "Decimal USD; zero in free preview."
          },
          "price_per_million_input_usd": {
            "type": [
              "string",
              "null"
            ],
            "description": "Effective rate for this request; null in preview."
          }
        },
        "required": [
          "input_tokens",
          "output_tokens",
          "cost_microusd",
          "cost_usd",
          "price_per_million_input_usd"
        ],
        "additionalProperties": false
      },
      "DecisionResponse": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "service_mode": {
            "enum": [
              "preview",
              "paid"
            ]
          },
          "answers": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ChoiceAnswer"
                },
                {
                  "$ref": "#/components/schemas/ScoreAnswer"
                },
                {
                  "$ref": "#/components/schemas/NoulAnswer"
                }
              ]
            },
            "description": "Keys match the question IDs in the request."
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "latency_ms": {
            "type": "number",
            "minimum": 0,
            "description": "Optional model timing."
          },
          "gateway_latency_ms": {
            "type": "number",
            "minimum": 0
          }
        },
        "required": [
          "model",
          "request_id",
          "service_mode",
          "answers",
          "usage",
          "gateway_latency_ms"
        ],
        "additionalProperties": false
      },
      "ModelsResponse": {
        "type": "object",
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "context": {
                  "type": "object",
                  "properties": {
                    "max_state": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "max_branch": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "strict": {
                      "type": "boolean"
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "models"
        ],
        "additionalProperties": false
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "description": "Field-level validation errors, when applicable.",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "field",
                "message"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "detail"
        ],
        "additionalProperties": false
      }
    }
  },
  "externalDocs": {
    "url": "https://shvydko.ai/docs",
    "description": "Human-readable documentation and runnable examples"
  }
}