POST /v1/systemone

The request and response contract for Choice, Score, and Noul through one HTTP endpoint.

HTTP and headers

Send an organization Bearer API key and UTF-8 JSON. A successful response has HTTP status 200. The endpoint returns a complete JSON response; streaming text generation is not supported.

POST · application/json

curl --fail-with-body "$SHVYDKO_BASE_URL/v1/systemone" \
  -H "Authorization: Bearer $SHVYDKO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Request fields

Field	Type	Rule
state	JSON	Required shared context
questions	object	1 to 32 questions; ID length is 1–100 characters
questions[id].type	string	choice, score, or noul
questions[id].instructions	JSON, optional	A clear text description of the task is recommended
questions[id].criteria	object / array	The format depends on the question type
model	string, optional	A name from GET /v1/models; omit to use the configured model

Additional top-level fields and unknown fields within a question are rejected. The temperature, messages, stream, and tools parameters are not part of this contract.

Response fields

Field	Meaning
answers	An object with the same IDs as questions
model	The public name of the configured model
request_id	Request ID for matching against Usage
service_mode	preview or paid
usage.input_tokens / output_tokens	Actual token accounting reported by the model service
usage.cost_microusd	Cost in integer microdollars; 1 USD = 1,000,000 microUSD
usage.cost_usd	The same cost as a decimal USD string
usage.price_per_million_input_usd	Applied rate; null in free preview
gateway_latency_ms	Gateway request processing time in milliseconds

Illustrative preview response structure; not a measurement

{
  "answers": {
    "team": {
      "type": "choice",
      "choice": "engineering",
      "probabilities": {
        "engineering": 0.88,
        "logistics": 0.04,
        "other": 0.08
      },
      "confidence": 0.82
    },
    "urgency": {
      "type": "score",
      "score": 1.1,
      "probabilities": {
        "0": 0.05,
        "1": 0.8,
        "2": 0.15
      },
      "legend": {
        "0": "An informational question; nothing is blocked",
        "1": "There is an inconvenience, but another way to complete the action is available",
        "2": "The action is completely blocked; prompt assistance is needed"
      },
      "confidence": 0.7
    },
    "alternative": {
      "type": "noul",
      "noul": 0.94
    }
  },
  "model": "shvydko-latest",
  "request_id": "req_example",
  "service_mode": "preview",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 20,
    "cost_microusd": 0,
    "cost_usd": "0.000000",
    "price_per_million_input_usd": null
  },
  "gateway_latency_ms": 245
}

Matching records and repeated requests

A successful response includes the x-shvydko-request-id header. It matches request_id in the JSON. Store it with your own task ID to find the record in Usage.

The API does not provide an idempotency contract for inference. A repeated POST is a new request. If the connection is lost after processing, blindly retrying may create a second charge in paid mode. Limit retries and check history before repeating a business action.