# POST /v1/systemone

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

Source: https://shvydko.ai/en/docs/api/systemone

## 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

```bash
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

```json
{
  "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.

## Related documentation

- [Keys and authentication](https://shvydko.ai/en/docs-markdown/api/authentication.md)
- [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md)
- [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md)
- [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md)