# Shvydko > Typed decisions over your context: Choice, Score and Noul. Operated by Codebridge Technology, Inc. ## API and integration - [OpenAPI 3.1 contract](https://shvydko.ai/openapi.json): Public bearer-key endpoints only; no SDK installation required. - [Full documentation](https://shvydko.ai/en/llms-full.txt): All current documentation as Markdown. - [Runtime configuration](https://shvydko.ai/api/config): Current mode, published price and request limits. Preview requests cost zero; do not infer paid billing from the published future price. ## Documentation - [First request](https://shvydko.ai/en/docs-markdown/quickstart.md): From a Playground example to a typed decision in your application. - [Context and questions](https://shvydko.ai/en/docs-markdown/concepts/context.md): Separate facts from the decision rule. One context can answer several independent questions. - [Choice](https://shvydko.ai/en/docs-markdown/primitives/choice.md): One named category from your options: a team, intent, route, or document class. - [Score](https://shvydko.ai/en/docs-markdown/primitives/score.md): A numeric score on a scale whose levels you describe in words. - [Noul](https://shvydko.ai/en/docs-markdown/primitives/noul.md): A statement score from 0 to 1: check whether a fact is present, a rule applies, or a condition is met. - [POST /v1/systemone](https://shvydko.ai/en/docs-markdown/api/systemone.md): The request and response contract for Choice, Score, and Noul through one HTTP endpoint. - [GET /v1/models](https://shvydko.ai/en/docs-markdown/api/models.md): Get the available model's name and context limits before integrating. - [Keys and authentication](https://shvydko.ai/en/docs-markdown/api/authentication.md): Organization API keys for your server, one-time secret display, and access revocation. - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md): Distinguish validation errors, limits, insufficient reservation balance, and model unavailability. - [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md): Three different limits: JSON size, model tokens, and organization request rate. - [The Shvydko model](https://shvydko.ai/en/docs-markdown/models.md): Typed decisions through one API. Capabilities, the current model card, and limitations. - [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md): Input-token pricing, one-time Stripe top-ups, reservations, and actual charges. - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md): How to read probabilities, confidence, and Noul, and choose thresholds for your workflow. - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md): From a working example to a reproducible evaluation of quality, cost, and latency. - [Python over HTTP](https://shvydko.ai/en/docs-markdown/integrations/python.md): A complete example using Python's standard library, with no separate SDK. - [JavaScript over HTTP](https://shvydko.ai/en/docs-markdown/integrations/javascript.md): Server-side fetch with status checking and a timeout, keeping the API key out of the browser. - [Shvydko for AI agents](https://shvydko.ai/en/docs-markdown/integrations/coding-agents.md): Give your agent the current contract, validate the request locally, and connect typed decisions to your server code. - [Routing support requests](https://shvydko.ai/en/docs-markdown/patterns/routing.md): A practical workflow: classify a request, check confidence and retain a manual route. ## Other resources - [Examples](https://shvydko.ai/en/examples): Runnable decision inputs, not customer outcome claims. - [Comparison and limitations](https://shvydko.ai/en/compare): Versions, methodology and limitations beside the diagnostic result. - [Terms](https://shvydko.ai/en/terms): Operator, credit and refund terms. - [Privacy](https://shvydko.ai/en/privacy): Data processing and account information. --- # First request From a Playground example to a typed decision in your application. Source: https://shvydko.ai/en/docs/quickstart ## 01. Try it in your account Create an account and open Playground. Add context, write a question, and choose Choice, Score, or Noul. Before running it, check the active organization: its keys, limits, and request history are shared by its members. Open the scenario “Where should this request go?” It is the same fictional payment failure shown on the homepage. Its full request is included below: in Playground, you can change one detail and check the new response. - [Open this example in Playground](https://shvydko.ai/en/console/playground?example=support-routing) - [Step-by-step Choice lesson](https://shvydko.ai/en/console/playground?lesson=choice) - [Step-by-step Score lesson](https://shvydko.ai/en/console/playground?lesson=score) - [Step-by-step Noul lesson](https://shvydko.ai/en/console/playground?lesson=noul) ## 02. Prepare your key and environment An organization owner or admin creates a key in API Keys. The full value is shown only when the key is created. Store it in a secret manager or a server-side environment variable. SHVYDKO_BASE_URL is the Shvydko address without a trailing slash. SHVYDKO_API_KEY is your secret key. Do not put the key in browser JavaScript, a repository, or an example link. ### API address · shell ```bash export SHVYDKO_BASE_URL='https://shvydko.ai' # Supply SHVYDKO_API_KEY through your environment's secret manager. ``` - [Create an API key](https://shvydko.ai/en/console/keys) ## 03. Save request.json One state contains the facts for all questions. team selects a team, impact rates the failure's impact, and human_review checks the urgent-review rule. Responses are returned under these same identifiers in answers. ### request.json · fictional example ```json { "state": "An online store customer reports: “For the last 15 minutes, no customer has been able to pay for an order by card. The page shows payment unavailable. Payment on delivery works. We checked on three different devices. No money is being charged to the cards.” Routing policy: website failures go to engineering; questions about charges and invoices go to finance; delivery times go to logistics. A payment-method outage affecting many customers requires urgent human review.", "questions": { "team": { "type": "choice", "instructions": "Which team should handle this request? Choose based on the main cause of the problem.", "criteria": { "engineering": "Engineering: website or integration failure", "finance": "Finance: invoices and refunds of charged payments", "logistics": "Logistics: shipping and delivery" } }, "impact": { "type": "score", "instructions": "Assess how the described issue affects placing orders.", "criteria": [ "Does not prevent placing orders", "Makes ordering harder for one customer", "Blocks one payment method for many customers", "Blocks every ordering method for all customers" ] }, "human_review": { "type": "noul", "instructions": "Under the stated policy, this request requires urgent human review." } } } ``` ## 04. Send the request Check the HTTP status before reading answers. Find request_id, usage.input_tokens, and usage.cost_usd in the response. Then check the request against Usage history in your account. Preview includes limited free runs. A published rate alone does not mean charging is enabled: service_mode reports the actual mode. ### Terminal ```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 ``` - [View usage](https://shvydko.ai/en/console/usage) ## 05. Compare with the recorded response This response was obtained from the public API 2026-10-17T03:28:15.407106Z for the request above. It is one saved run on a fictional support request, not a result from your browser or an assessment of quality across all tasks. Your repeated request may return different values. The API returned the engineering team, an impact score of 1.9987 on a 0–3 scale, and a Noul value of 0.9934 for the urgent-review rule. Confidence values are not measured proportions of correct responses. In this run, the model reported 652.5 ms of processing; the request from the account server to the model took 784.29 ms; the full HTTPS request from the client that saved the recording took 1029.885 ms. These are different measurement boundaries for one run, not a speed guarantee. In preview mode, the charge was $0. ### API response · recorded 2026-10-17 ```json { "answers": { "team": { "type": "choice", "choice": "engineering", "probabilities": { "engineering": 0.9999, "finance": 0.0001, "logistics": 0 }, "confidence": 0.9998 }, "impact": { "type": "score", "score": 1.9987, "probabilities": { "0": 0.0007, "1": 0, "2": 0.9992, "3": 0.0001 }, "confidence": 0.9986, "legend": { "0": "Does not prevent placing orders", "1": "Makes ordering harder for one customer", "2": "Blocks one payment method for many customers", "3": "Blocks every ordering method for all customers" } }, "human_review": { "type": "noul", "noul": 0.9934 } }, "usage": { "input_tokens": 208, "output_tokens": 208, "cost_microusd": 0, "cost_usd": "0.000000", "price_per_million_input_usd": null }, "latency_ms": 652.5, "model": "shvydko-latest", "request_id": "req_uGar8EBEH-ufcmkx9dEtosrx", "service_mode": "preview", "gateway_latency_ms": 784.29 } ``` - [Full request and response recording as JSON](https://shvydko.ai/research/support-routing-recorded-en-2026-10-17.json) ## 06. Pass the decision to your code The engineering key means the technical queue, finance means payment review, and logistics means delivery support. An unknown or missing key is left for manual review. The function below prepares the next step; your integration connects it to your ticketing system. Before enabling automatic routing, evaluate decisions on your own examples and define a manual-review rule. One successful run is not enough to assess quality across all your support requests. ### JavaScript · next queue ```javascript function nextSupportStep(result) { const queues = new Map([ ["engineering", "technical_support"], ["finance", "billing_review"], ["logistics", "delivery_support"], ]); const answer = result?.answers?.team; const queue = answer?.type === "choice" && queues.has(answer.choice) ? queues.get(answer.choice) : "manual_review"; return { queue, request_id: result?.request_id ?? null }; } // Returns a proposed queue; your integration performs the next action. const nextStep = nextSupportStep(result); console.log(nextStep); ``` - [Run with Python](https://shvydko.ai/en/docs/integrations/python) - [Run with JavaScript](https://shvydko.ai/en/docs/integrations/javascript) - [Evaluate on your own data](https://shvydko.ai/en/docs/evaluation) ## Related documentation - [Context and questions](https://shvydko.ai/en/docs-markdown/concepts/context.md) - [POST /v1/systemone](https://shvydko.ai/en/docs-markdown/api/systemone.md) - [Python over HTTP](https://shvydko.ai/en/docs-markdown/integrations/python.md) --- # Context and questions Separate facts from the decision rule. One context can answer several independent questions. Source: https://shvydko.ai/en/docs/concepts/context ## State: task facts state accepts JSON: a string, object, array, or any other JSON value. Text works for an email; an object with fields works for a ticket. Send the data needed for the decision: a support message, order status, rules, or a document excerpt. A URL in the text does not automatically load the page. Extract its content in your own application and send the relevant excerpt. Files, images, audio, and video are not separate supported inputs for this API. ### Structured state ```json { "state": { "message": "I want to change the delivery address", "shipment_status": "not_dispatched", "policy": "The address can be changed before dispatch" }, "questions": { "change_allowed": { "type": "noul", "instructions": "Does the provided rule allow changing the address for this order?" } } } ``` ## Questions: the decision rule questions is an object in which each question has its own identifier, type, optional instructions, and criteria in the appropriate format. Give each question one clear task and explain the differences between criteria. Questions in one request share the same context. Do not ask one question to use another question's answer. For a dependent decision, make a second request in your code after receiving the first response. - Choice: named categories from which to select one. - Score: ordered scale levels from first to last. - Noul: a statement or question with a yes/no answer. ## Plan for unknowns too Add an “insufficient information” category if the task allows uncertainty. If a fact is missing, the model does not automatically retrieve it from your database or other requests. Input text may contain instructions from a third party. Define the task in your own instructions, separate quotations from rules, and test conflicting instructions on your own dataset. JSON alone does not guarantee protection against incorrect decisions. ## Storage and sharing Usage history stores request metadata, tokens, timing, status, and cost. A saved example in Shares separately contains state and questions, so review its contents before sharing. New examples are organization-only by default. Public access must be chosen explicitly and also requires the organization's permission. Remove personal data, secrets, and real customer documents from demonstrations. - [Privacy policy](https://shvydko.ai/en/privacy) - [Saved examples](https://shvydko.ai/en/console/shares) ## Related documentation - [Choice](https://shvydko.ai/en/docs-markdown/primitives/choice.md) - [Score](https://shvydko.ai/en/docs-markdown/primitives/score.md) - [Noul](https://shvydko.ai/en/docs-markdown/primitives/noul.md) - [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md) --- # Choice One named category from your options: a team, intent, route, or document class. Source: https://shvydko.ai/en/docs/primitives/choice ## Describe the categories criteria is an object with 1–255 options. Keys are stable identifiers for your code; values explain the categories. Names must be unique within the JSON object. Choice returns exactly one category. For several independent attributes, create several Noul questions; for an ordered scale, use Score. ### Choice in a complete request ```json { "state": "Card payment is not working. Cash on delivery is available. The customer asks for help placing an order.", "questions": { "team": { "type": "choice", "instructions": "Which team should handle this request?", "criteria": { "engineering": "Website and payment integration failures", "logistics": "Order delivery and collection", "other": "Questions outside these categories or insufficient information" } } } } ``` ## Read choice and probabilities answers.team.choice is the key of the selected category. probabilities contains numeric estimates for all your keys; confidence is a separate confidence indicator from 0 to 1. Use an allowlist of keys for business actions. Low confidence or the other category can lead to manual review. Choose the threshold using your own labeled data. ### Illustration of answers.team; not a run result ```json { "type": "choice", "choice": "engineering", "probabilities": { "engineering": 0.88, "logistics": 0.04, "other": 0.08 }, "confidence": 0.82 } ``` > The probabilities and confidence values do not guarantee a correct decision. ## Make criteria useful - Describe what belongs in each category, rather than using only a short name. - Remove categories with the same meaning or explain how to choose between them. - Include borderline cases in evaluation, not just obvious positive cases. - Do not change the meaning of identifiers without updating the code that handles the response. ## Related documentation - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [Routing support requests](https://shvydko.ai/en/docs-markdown/patterns/routing.md) - [Score](https://shvydko.ai/en/docs-markdown/primitives/score.md) --- # Score A numeric score on a scale whose levels you describe in words. Source: https://shvydko.ai/en/docs/primitives/score ## Define an ordered scale criteria is an array of 1–255 descriptions ordered from the first level to the last. Indices start at 0. With three criteria, the result is between 0 and 2. Describe an observable difference between levels. For urgency, this could be the impact on work and the availability of a workaround; for relevance, how well something matches a specific request. ### Score in a complete request ```json { "state": "Card payment is not working. Cash on delivery is available. The customer asks for help placing an order.", "questions": { "urgency": { "type": "score", "instructions": "Rate the urgency of the request using the levels provided.", "criteria": [ "An informational question; nothing is blocked", "There is an inconvenience, but another way to complete the action is available", "The action is completely blocked; prompt assistance is needed" ] } } } ``` ## Score can be fractional score estimates a position on the scale; it is not a text label for a level. probabilities uses string index keys: “0”, “1”, “2”. confidence is returned separately. The service also returns legend: level descriptions keyed by their indices. Decide in your code whether you need a continuous score, a rounded level, or a threshold decision. Do not convert score to a probability percentage: your criteria define the scale. ### Illustration of answers.urgency; not a run result ```json { "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 } ``` ## Compare using the same scale Use the same instructions and criteria to rank multiple records. If you change the number or meaning of levels, old and new scores will no longer be directly comparable. Check not only average error, but also cases where a one-level error has different consequences. Critical thresholds need a separate evaluation of false negatives and false positives. ## Related documentation - [Choice](https://shvydko.ai/en/docs-markdown/primitives/choice.md) - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md) --- # Noul A statement score from 0 to 1: check whether a fact is present, a rule applies, or a condition is met. Source: https://shvydko.ai/en/docs/primitives/noul ## State one condition type: “noul” suits a question with two sides: yes and no. You can omit criteria or provide descriptions with the keys true and false. If a question contains several independent conditions, it is better to separate them. Clarify whether you are checking for a fact in the context or drawing a conclusion from a rule. “Is a return mentioned?” and “Is a return allowed?” are different tasks. ### Noul in a complete request ```json { "state": "Card payment is not working. Cash on delivery is available. The customer asks for help placing an order.", "questions": { "alternative": { "type": "noul", "instructions": "Does the context specify another available payment method?", "criteria": { "true": "Another payment method is available", "false": "No alternative is specified, or it is unavailable" } } } } ``` ## Read noul answers.alternative.noul is a number from 0 to 1. Higher values indicate stronger support for true. Separate confidence and probabilities fields for Noul are not part of this contract. You can use 0.5 as an initial experimental threshold, but a production threshold depends on the consequences of errors. You can leave a manual-review zone between acceptance and rejection thresholds. ### Illustration of answers.alternative; not a run result ```json { "type": "noul", "noul": 0.94 } ``` > The example value 0.94 demonstrates the numeric format. It is not a measured probability of success for your workflow. ## Test negation and missing information - Include texts with words such as “not”, “previously”, “so far”, and conditional statements. - Distinguish between a fact not being mentioned and an explicit denial, if that matters for your task. - Test quotations, forwarded messages, and conflicting information. - Keep human review available for consequential actions. ## Related documentation - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [Context and questions](https://shvydko.ai/en/docs-markdown/concepts/context.md) - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md) --- # 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) --- # GET /v1/models Get the available model's name and context limits before integrating. Source: https://shvydko.ai/en/docs/api/models ## Get the current model card The endpoint requires a valid API key. It returns Shvydko's public name and current limits without running an evaluation. The same content is available to authenticated accounts via GET /api/models. Pass models[0].name in the model field, or omit model to use the current version of the service. ### GET · Bearer API key ```bash curl --fail-with-body "$SHVYDKO_BASE_URL/v1/models" \ -H "Authorization: Bearer $SHVYDKO_API_KEY" ``` ## What the fields mean Context fields may be absent. Do not substitute invented values. If context contains max_state and max_branch, the former limits the shared state and the latter limits state together with an individual question branch. strict: true in the context card means the service strictly enforces the limits. Even if a request fits the gateway's JSON limit, it may exceed the model's token context limit. | Model field | Meaning | | --- | --- | | name | Public name for POST /v1/systemone | | context | Current context limits, if provided by the service | ## Availability and version HTTP 502 means the connected model's card could not be retrieved; 503 means the model service is not configured. A successful GET checks metadata availability, but does not measure inference quality or speed. shvydko-latest refers to the current version of the service. It may be updated. If your workflow requires a fixed version, arrange this before launch; the public API currently has no separate parameter to pin one. ## Related documentation - [The Shvydko model](https://shvydko.ai/en/docs-markdown/models.md) - [Keys and authentication](https://shvydko.ai/en/docs-markdown/api/authentication.md) - [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md) --- # Keys and authentication Organization API keys for your server, one-time secret display, and access revocation. Source: https://shvydko.ai/en/docs/api/authentication ## Creating a key An owner or admin opens API Keys in the relevant organization and gives the key a clear name, such as support-staging. The secret is displayed once. The list retains the name and prefix for identification. A key belongs to an organization: its balance, limits, and Usage apply to all its keys. Selecting another organization in your account does not transfer an existing key. - [Manage keys](https://shvydko.ai/en/console/keys) ## Sending the key Call the API from a trusted server. Do not put the secret in public NEXT_PUBLIC_ variables or localStorage. For a browser application, create your own server endpoint with user authentication. External /v1 endpoints use a Bearer key. The account's session cookie and active-organization header are not required for /v1 integration. ### HTTP header ```http Authorization: Bearer ``` ## Rotation and revocation A revoked, unknown, or missing key returns HTTP 401. Do not log Authorization or include it in a support request about an error. - Create a new key and update the secret in your server environment. - Test a GET /v1/models request with the new key. - Revoke the old key in your account. - If a key leaks, revoke it immediately; its full value cannot be retrieved again. ## Related documentation - [First request](https://shvydko.ai/en/docs-markdown/quickstart.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) - [Routing support requests](https://shvydko.ai/en/docs-markdown/patterns/routing.md) --- # Errors and retries Distinguish validation errors, limits, insufficient reservation balance, and model unavailability. Source: https://shvydko.ai/en/docs/api/errors ## Read the HTTP status and detail An error is returned with an unsuccessful HTTP status and a detail field. Validation errors may also include errors: a list of fields and messages. Do not expect answers in such a response. ### Example validation error structure ```json { "detail": "Request validation failed", "errors": [ { "field": "body.questions", "message": "Questions must use supported types" } ] } ``` > The example wording is illustrative. Handle the status and structure, rather than the exact wording of detail. ## Statuses | HTTP | Cause | What to do | | --- | --- | --- | | 401 | The key is missing, unknown, or revoked | Check the server secret; do not retry with the same key | | 402 | Insufficient available balance for a reservation in paid mode | Check the balance and active reservations | | 403 | The organization is suspended for billing review | Check the organization's status; do not bypass it with new keys | | 409 | The request reservation has already been finalized or expired | Check Usage; do not automatically repeat the action | | 413 | The JSON exceeds the byte limit | Shorten the context or split the task | | 422 | Invalid structure, model name, or rejected context | Correct the request or reduce the context | | 429 | Per-minute limit or daily preview quota | Respect Retry-After if present; daily quotas reset at 00:00 UTC | | 502 | The model is unavailable, returned an invalid response, or timed out | Retry within a limit and with a delay; check Usage after a lost connection | | 503 | The model service is not connected | Check the service status later | ## Retries must be bounded For a per-minute 429, use Retry-After and a small random delay across clients. The daily preview quota may return 429 without this header: the message will indicate a reset at 00:00 UTC. Do not retry 401, 402, 403, 413, or 422 without addressing the cause. For network failures and 502, set a small attempt limit and a total time budget. POST /v1/systemone provides no idempotency guarantee. The gateway does not charge credits for a request it completed with a model error. Losing the response on your client is a different situation: the server may already have completed the request successfully. ## Related documentation - [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md) - [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md) - [Python over HTTP](https://shvydko.ai/en/docs-markdown/integrations/python.md) - [JavaScript over HTTP](https://shvydko.ai/en/docs-markdown/integrations/javascript.md) --- # Limits and context Three different limits: JSON size, model tokens, and organization request rate. Source: https://shvydko.ai/en/docs/api/limits ## Current configuration Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability. ## Check the current configuration The current configuration panel reads its settings from GET /api/config. They may change between deployments. More keys do not increase an organization's quota. Body size is measured in UTF-8 bytes, while model context is measured in tokens. Text in any language, JSON syntax, and criteria descriptions take up space. Character count is not an exact token count. | Limit | What it limits | | --- | --- | | max_request_bytes | The full JSON request in bytes | | max_questions | The number of questions in one request | | requests_per_minute | The organization's shared API and Playground request rate | | preview_request_limit | The organization's daily preview request count | | preview_global_request_limit | Daily preview capacity across the entire service | | reserve_tokens / max_input_tokens | The gateway's upper bound for usage accounting and financial reservations; this is not the model's context size | ## The model service defines the context Read the current state and question-branch limits in GET /v1/models → models[].context. The max_input_tokens value from /api/config does not mean a state of that size will fit the model. A large request can pass the byte-size check and still be rejected for exceeding model context. Select relevant excerpts, remove repetition, and split independent documents into separate requests. Evaluate long-context quality separately. ## Preview and quota resets Preview has separate daily limits for each organization and the entire service; they reset at 00:00 UTC. Requests accepted for processing that later fail also consume daily quota. HTTP errors before a request is accepted do not create an inference record. An organization shares one per-minute quota across API and Playground. For parallel processing, limit concurrent requests in your application. ## Related documentation - [GET /v1/models](https://shvydko.ai/en/docs-markdown/api/models.md) - [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) --- # The Shvydko model Typed decisions through one API. Capabilities, the current model card, and limitations. Source: https://shvydko.ai/en/docs/models ## Current configuration Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability. ## Suitable tasks Shvydko takes context and questions and returns Choice, Score, or Noul. Typical tasks include routing support requests, classifying documents, scoring relevance, and checking conditions. The API works with text and JSON context. It does not provide open-ended chat generation, web search, agent tools, images, or Box. For a multi-step workflow, your application combines several decisions with its own data and actions. - [Example tasks](https://shvydko.ai/en/examples) ## Available model card GET /v1/models returns the connected service's actual model card, including context when available. The name in the current configuration panel is the configured alias; having a configuration does not prove that inference is currently working. The public name may remain the same after a service update. Selecting a separate fixed version through this API is not currently supported. ### Get current metadata ```bash curl --fail-with-body "$SHVYDKO_BASE_URL/v1/models" \ -H "Authorization: Bearer $SHVYDKO_API_KEY" ``` ## Quality depends on the task A valid JSON structure does not mean the decision is correct. Evaluate each required language separately, including English and Ukrainian, along with ambiguous wording, new categories, and your domain's context on your own labeled dataset. Demo runs show the integration and response format in action. They do not establish overall accuracy, probability calibration, or superiority over another model. Individual research comparisons have their own datasets and limits on their findings. - [Comparisons and measurement limitations](https://shvydko.ai/en/compare) ## Before using it in a workflow - Record the version of your criteria, your test dataset, and your rule for handing cases to a person. - Check current context limits and behavior when they are exceeded. - Measure latency and the error rate under your own workload. - Do not use the model as the sole basis for a consequential, irreversible decision. ## Related documentation - [GET /v1/models](https://shvydko.ai/en/docs-markdown/api/models.md) - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md) - [Pricing and usage accounting](https://shvydko.ai/en/docs-markdown/pricing.md) --- # Pricing and usage accounting Input-token pricing, one-time Stripe top-ups, reservations, and actual charges. Source: https://shvydko.ai/en/docs/pricing ## Current configuration Runtime values are not frozen in this document. Read GET https://shvydko.ai/api/config for the current service mode, pricing and gateway limits. Read authenticated GET /v1/models for model context limits. Configuration alone does not prove inference availability. ## Rate and mode are separate Shvydko's published rate is $0.042 per million input tokens; output tokens are free. The current service mode appears in the current configuration panel. In preview, requests are free within the quota, even when a rate has been published. service_mode in the response determines the request's mode. usage.price_per_million_input_usd is the applied rate; in preview it is null and cost_microusd is 0. Top-up availability is separately indicated by billing_enabled. > Check the mode before starting a workload. Having money in the balance does not enable paid mode by itself. ## Calculating a paid request Actual cost is calculated from usage.input_tokens returned by the model service. The gateway stores money as integer microUSD and rounds each successful paid request up to the next microUSD. At a rate of 0.042, a request with 1,000 input tokens costs 42 microUSD, or $0.000042. A 49-token request costs 3 microUSD after rounding. These are arithmetic examples, not estimates of your average request size. ### Formula · paid mode ```text cost_microusd = ceil(input_tokens × price_per_million_input_usd) cost_usd = cost_microusd / 1_000_000 preview: cost_microusd = 0 ``` ## Reservation before execution Before a paid request, the gateway reserves the maximum amount based on its reserve_tokens limit. If balance minus active reservations is insufficient, it returns 402 without calling the model. On success, the actual amount is charged and the rest of the reservation is released. A model error releases the reservation without a charge. For concurrent requests, the available balance accounts for all active reservations. Because of the reservation, even a short request may need more available funds than its final cost. Compare available balance and reserve, not just the total balance. ## Review usage for a period In Usage, choose a preset period or custom UTC dates: both dates are inclusive, with a maximum of 90 days. Filter API, Playground, or all requests. The chart supports hourly and daily views and includes intervals with no requests. History shows 100 requests per page. The snapshot stays stable as you page through it; refresh to include new requests. CSV contains all records for the selected period and source, not just the current page. Cost comes from the actual stored accounting for each request—a change to the published rate does not recalculate older records. Usage exports contain metadata and accounting, not the original text of your context. To reconcile an individual run, use request_id from the API response or evaluation report. - [View usage and CSV](https://shvydko.ai/en/console/usage) ## Balance, payments, and documents When top-ups are enabled, a workspace owner or admin can choose a one-time top-up from $5 to $1,000 and pay on Stripe's secure checkout page. On return, the account checks that specific payment and updates the balance. Credits are added only after the server confirms payment. Simply following a success link does not change the balance. Billing shows the available balance, reservations, transaction history, and pending top-ups. If a checkout page is still valid, you can resume it from the list. If you were charged but confirmation is delayed, check the status later or contact support; you do not need to pay again. A receipt is available for a confirmed payment once Stripe can issue it. Payment details can be managed in Stripe; the billing email and organization name can be changed in workspace settings. A refund appears in history and changes the credit balance; if credits have already been spent, the balance may become negative. Codebridge Technology, Inc. accepts payment for Shvydko API credits through Stripe in US dollars. Unused purchased credits can be refunded on request, including when closing an account; we reconcile the amount against top-ups and actual usage. Email business@codebridge.tech and identify the payment in your history. The refund and billing-error process is described in the terms of service. A promo code can be redeemed once per workspace in Billing and adds separate free credits. These are spent first and cannot be refunded for cash. A code may have a redemption deadline and a limit on total redemptions. Auto top-up is available only after the feature is enabled in paid mode. An admin separately agrees to the balance threshold, amount, and UTC monthly cap, and saves a card through Stripe. No charges are initiated in preview. An error or unknown result pauses auto top-up; there is no automatic repeat charge. Disabling it does not cancel an already submitted payment. Creating custom invoices is not supported. - [Open Billing](https://shvydko.ai/en/console/billing) - [Terms of service](https://shvydko.ai/en/terms) ## Related documentation - [Limits and context](https://shvydko.ai/en/docs-markdown/api/limits.md) - [POST /v1/systemone](https://shvydko.ai/en/docs-markdown/api/systemone.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) --- # Decision confidence How to read probabilities, confidence, and Noul, and choose thresholds for your workflow. Source: https://shvydko.ai/en/docs/confidence ## Three different signals Do not replace confidence with the largest probabilities value or interpret Score as a probability. Keep the fields separate when analyzing quality. High confidence does not rule out errors. A value of 0.9 is not a promise of 90% correct decisions on your traffic: that must be tested on labeled data. | Signal | How to read it | | --- | --- | | Choice probabilities | A distribution of estimates across your named categories | | Score probabilities | A distribution of estimates across ordered scale indices | | Choice / Score confidence | A separate confidence indicator from 0 to 1 | | Noul noul | A score for true from 0 to 1; no separate confidence field | ## The threshold depends on the cost of errors First decide which is worse for your workflow: missing a relevant case or triggering incorrectly. Choose a threshold on a separate calibration dataset and validate it on data that was not used to select it. Compare the accuracy of accepted decisions with coverage—the proportion of cases the system handles. Raising the threshold usually changes both coverage and the mix of errors; evaluate both. ## Leave a route for uncertainty - Define manual review or another handler for uncertain decisions. - For Noul, you can use two boundaries: accept true, accept false, and review the middle. - For Choice, add a category covering unknown or out-of-scope requests. - Repeat the evaluation after changes to criteria, the data domain, or the model service. > Thresholds from a learning example do not replace evaluation on your own data. ## Related documentation - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md) - [Routing support requests](https://shvydko.ai/en/docs-markdown/patterns/routing.md) - [Noul](https://shvydko.ai/en/docs-markdown/primitives/noul.md) --- # How to evaluate the model From a working example to a reproducible evaluation of quality, cost, and latency. Source: https://shvydko.ai/en/docs/evaluation ## Start with the task and data Define success before running: which categories are correct, what error is acceptable, and which cases require manual review. Collect examples from your real distribution, removing or appropriately protecting personal data. Separate data used to develop wording, choose thresholds, and perform final evaluation. Keep examples from the same document, customer, or template in the same split so near-duplicates do not give a misleading impression of quality. - Positive and negative examples, including rare categories. - Each required language, including English and Ukrainian, with separate results. - Negation, conflicting facts, missing information, and third-party instructions in the context. - Long texts and cases near the allowed context limit. ## Choose metrics for the decision Calculate metrics over all planned records. Timeouts and format errors must not be silently excluded. To compare models, use the same records, criteria, and scoring rules. | Task | What to measure | | --- | --- | | Choice | Accuracy, confusion between categories, and per-category results | | Score | Error against the reference scale and errors near the business threshold | | Noul | False positives and false negatives at the chosen threshold | | Manual review | Coverage and the error rate among automatically accepted decisions | | Operations | p50/p95 latency, HTTP error rate, input tokens, and cost | ## Record the evaluation conditions - The dataset version and checksum, and its splits. - The exact state, instructions, and criteria, or their controlled version. - The date, endpoint, public name, and current service limits; the shvydko-latest name may stay the same after an update. - request_id, response, tokens, billing mode, cost, and latency. - The threshold rule and list of exclusions, defined before the final calculation. > Do not publish API keys, personal data, or private documents with the report. ## Run your dataset in your account Open Evaluations and upload a JSONL file: one object per line, up to 100 examples. Each record contains id, state, questions, and expected. For Choice, expected contains the correct category key; for Noul, true or false; for Score, an object with min and max for the acceptable result. The account validates the file before running and sends requests sequentially using your active organization. This tool uses a threshold of 0.5 for Noul. Results, errors, and usage are saved in a report you can download and reopen without new model calls. The dataset and report stay in your browser until you export them; there is no server-side evaluation dataset storage. During a run, context is sent to the service just as in Playground. A synthetic example checks the execution workflow and is not evidence of quality on your data. ### One evaluation.jsonl line · fictional example ```json {"id":"support-001","state":"Card payment is not working, but cash on delivery is available.","questions":{"team":{"type":"choice","instructions":"Which team should investigate the failure?","criteria":{"engineering":"Technical payment failure","logistics":"Delivery problem"}}},"expected":{"team":"engineering"}} ``` - [Open Evaluations](https://shvydko.ai/en/console/evaluations) - [Download an example dataset](https://shvydko.ai/examples/en/workflows.jsonl) ## Demos, research, and your evaluation Ready-made examples demonstrate the format and scenario. A research report describes a specific dataset and conditions. Your own evaluation answers whether the service suits a particular product. The Shvydko comparison page presents available research results and their limitations. Evaluations in your account help test your own dataset; they do not replace an independent holdout, data-shift analysis, or calibration testing. - [Read the research comparison](https://shvydko.ai/en/compare) - [Explore examples](https://shvydko.ai/en/examples) ## Related documentation - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [The Shvydko model](https://shvydko.ai/en/docs-markdown/models.md) - [Routing support requests](https://shvydko.ai/en/docs-markdown/patterns/routing.md) --- # Python over HTTP A complete example using Python's standard library, with no separate SDK. Source: https://shvydko.ai/en/docs/integrations/python ## Prepare the input Save request.json from the first-request page. Supply SHVYDKO_BASE_URL and SHVYDKO_API_KEY through the server process environment. The example uses json, os, and urllib.request from the standard library. - [Copy request.json](https://shvydko.ai/en/docs/quickstart#request) ## Request, status, and response This example deliberately does not retry POST automatically. Add your own bounded retry mechanism after considering the HTTP status and risk of duplicate processing. ### request.py · Python 3 ```python import json import os import urllib.error import urllib.request base_url = os.environ["SHVYDKO_BASE_URL"].rstrip("/") api_key = os.environ["SHVYDKO_API_KEY"] with open("request.json", encoding="utf-8") as source: payload = json.load(source) request = urllib.request.Request( base_url + "/v1/systemone", data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), headers={ "Authorization": "Bearer " + api_key, "Content-Type": "application/json", "User-Agent": "ShvydkoClient/1.0", }, method="POST", ) try: with urllib.request.urlopen(request, timeout=150) as response: result = json.load(response) except urllib.error.HTTPError as error: # Do not log the API key or the original customer context. try: detail = json.loads(error.read()).get("detail", "Request failed") except (ValueError, AttributeError): detail = "Non-JSON error response" retry_after = error.headers.get("Retry-After") raise SystemExit( f"Shvydko HTTP {error.code}: {detail}; Retry-After={retry_after}" ) except (urllib.error.URLError, TimeoutError) as error: raise SystemExit( "Network failure; check Usage before repeating a paid request" ) from error print("request_id:", result["request_id"]) print("team:", result["answers"]["team"]["choice"]) print("input_tokens:", result["usage"]["input_tokens"]) print("cost_usd:", result["usage"]["cost_usd"]) ``` ## Connecting to your application - Keep the secret in the server environment, separately for each development environment. - Pass only validated fields and allowed categories to business logic. - Limit concurrency according to the organization's quota. - Associate request_id with your task ID without logging secrets. > This is a direct Shvydko HTTP client. It does not claim a separate official Python SDK or compatibility with all third-party SDKs. ## Related documentation - [First request](https://shvydko.ai/en/docs-markdown/quickstart.md) - [POST /v1/systemone](https://shvydko.ai/en/docs-markdown/api/systemone.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) --- # JavaScript over HTTP Server-side fetch with status checking and a timeout, keeping the API key out of the browser. Source: https://shvydko.ai/en/docs/integrations/javascript ## Run on the server The example uses Node.js with built-in fetch and AbortSignal.timeout. Save it as request.mjs and take request.json from the quickstart. SHVYDKO_BASE_URL and SHVYDKO_API_KEY must be available to the server process. In a web application, call Shvydko from your own protected server endpoint. Do not put the secret in a client React component, HTML, or a public bundle. - [Copy request.json](https://shvydko.ai/en/docs/quickstart#request) ## Request with fetch ### request.mjs · server-side JavaScript ```javascript import { readFile } from "node:fs/promises"; const baseUrl = process.env.SHVYDKO_BASE_URL?.replace(/\/$/, ""); const apiKey = process.env.SHVYDKO_API_KEY; if (!baseUrl || !apiKey) throw new Error("Missing server configuration"); const payload = JSON.parse(await readFile("request.json", "utf8")); let response; try { response = await fetch(baseUrl + "/v1/systemone", { method: "POST", headers: { Authorization: "Bearer " + apiKey, "Content-Type": "application/json", }, body: JSON.stringify(payload), signal: AbortSignal.timeout(150_000), }); } catch { throw new Error("Network failure; check Usage before retrying a paid request"); } const body = await response.json().catch(() => null); if (!response.ok) { const detail = typeof body?.detail === "string" ? body.detail : "Request failed"; const retryAfter = response.headers.get("Retry-After"); throw new Error( "Shvydko HTTP " + response.status + ": " + detail + "; Retry-After=" + retryAfter ); } if (!body?.answers || !body?.usage || !body?.request_id) { throw new Error("Unexpected response shape"); } console.log({ requestId: body.request_id, team: body.answers.team.choice, inputTokens: body.usage.input_tokens, costUsd: body.usage.cost_usd, }); ``` ## Integrate into a controlled workflow Check the status before reading answers. For business actions, validate choice against an allowlist and numeric values against expected bounds. A network timeout on your client does not prove the server failed to execute the request. The example requires no SDK and does not assume support for OpenAI chat/completions. Use the /v1/systemone contract. ## Related documentation - [First request](https://shvydko.ai/en/docs-markdown/quickstart.md) - [Keys and authentication](https://shvydko.ai/en/docs-markdown/api/authentication.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) --- # Shvydko for AI agents Give your agent the current contract, validate the request locally, and connect typed decisions to your server code. Source: https://shvydko.ai/en/docs/integrations/coding-agents ## Documentation your agent can read llms.txt contains an index of topics and links to Markdown. llms-full.txt contains the full text of those same pages. OpenAPI describes only the public GET /v1/models and POST /v1/systemone endpoints that use an API key. These files are accessible without signing in; model requests require a key. Mode, rates, and quotas may change. Read /api/config and get model context through GET /v1/models. A published rate does not mean paid mode is enabled: requests cost zero in preview. - [Agent index](https://shvydko.ai/en/llms.txt) - [Full documentation text](https://shvydko.ai/en/llms-full.txt) - [OpenAPI 3.1 JSON](https://shvydko.ai/openapi.json) ## A task for your coding agent ### Copy this task into your agent's workspace ```text Connect Shvydko to my server application. 1. Read https://shvydko.ai/en/llms.txt and https://shvydko.ai/openapi.json. 2. Use the /v1/systemone HTTP API. Do not install an invented SDK or use chat/completions. 3. Read SHVYDKO_API_KEY only from the server environment. Do not expose it in code, logs, URLs, the browser, or messages. 4. Prepare a request: state contains task facts; questions contains Choice, Score, or Noul with clear criteria and a manual route for uncertainty. 5. Check the HTTP status, response structure, request_id, and usage. Handle 401, 402, 403, 409, 413, 422, 429, 502, and 503. Do not retry POST automatically after a network timeout. 6. Add local checks for a valid response, an error, and an unknown category. The model only proposes a decision; my application performs the external action after its own validation. 7. Show the payload without secrets before making a real call. At my request, make one controlled call and check usage. ``` > This is an instruction for your coding agent, not a separate MCP server or published SDK. Access to the documentation does not grant access to your account. ## Turn the decision into a tool In your agent's tool registry, create a server function named evaluate_decision with state and questions parameters matching the DecisionRequest schema in OpenAPI. You can omit the model name: the service will select the current public model. The function should return validated answers, request_id, and usage. Do not let a model response choose an HTTP request destination, payment recipient, or other external action on its own. If one step depends on the previous one, validate the first response before building the next request in code. - [Server function using fetch](https://shvydko.ai/en/docs/integrations/javascript#code) - [Python HTTP client](https://shvydko.ai/en/docs/integrations/python#code) - [Decision with a manual route](https://shvydko.ai/en/docs/patterns/routing#decision) ## What to check before launch - The request shape matches OpenAPI, the question has a stable ID, and the criteria cover your allowed outcomes. - An invalid key, request limit or service outage must not trigger an external action. - A mock response tests only your code; assess decision quality on your own labeled examples. - After an authorized real run, request_id, tokens and cost_usd agree with Usage in the console. ## Related documentation - [First request](https://shvydko.ai/en/docs-markdown/quickstart.md) - [POST /v1/systemone](https://shvydko.ai/en/docs-markdown/api/systemone.md) - [Errors and retries](https://shvydko.ai/en/docs-markdown/api/errors.md) - [JavaScript over HTTP](https://shvydko.ai/en/docs-markdown/integrations/javascript.md) --- # Routing support requests A practical workflow: classify a request, check confidence and retain a manual route. Source: https://shvydko.ai/en/docs/patterns/routing ## Decide before acting Imagine a support service that routes technical failures to engineering, payments to finance and delivery issues to logistics. Shvydko returns a category; your application decides whether there is enough information to route automatically. Use the team question from the quickstart. Add examples mentioning both payment and delivery to test the rule for identifying the main reason for contact. - [Example context and criteria](https://shvydko.ai/en/docs/quickstart#request) ## Define a safe function result reviewed_threshold is a threshold you have validated, not a universal constant. Start by collecting suggested routes and comparing them with agents' decisions. Enable automatic execution only after evaluation. ### Python · no external actions ```python def decide_route(result, reviewed_threshold): answer = result["answers"]["team"] choice = answer.get("choice") confidence = answer.get("confidence") allowed = {"engineering", "finance", "logistics"} if ( choice not in allowed or not isinstance(confidence, (int, float)) or confidence < reviewed_threshold ): return {"route": "manual_review", "request_id": result["request_id"]} return {"route": choice, "request_id": result["request_id"]} # Pass a threshold selected on your own labelled calibration data. # This function chooses a route; it does not create a ticket or send a message. ``` ## When to add a second question You can add an independent urgency assessment as a Score question in the same request, or check whether a necessary fact is present with Noul. If the second decision depends on the selected category, create a separate request after receiving the first response. Keep your own ticket ID and the request_id. Before taking an external action, check whether it has already been performed for that ticket: your application must ensure the business operation is idempotent. ## What to monitor after launch - The share of cases requiring manual review and errors in each category. - New inquiry topics that do not fit an existing category. - Latency, HTTP errors and costs by request volume. - Changes in results after editing criteria or updating the model. - [Check Usage](https://shvydko.ai/en/console/usage) - [Evaluation plan](https://shvydko.ai/en/docs/evaluation) ## Related documentation - [Choice](https://shvydko.ai/en/docs-markdown/primitives/choice.md) - [Decision confidence](https://shvydko.ai/en/docs-markdown/confidence.md) - [How to evaluate the model](https://shvydko.ai/en/docs-markdown/evaluation.md) - [Python over HTTP](https://shvydko.ai/en/docs-markdown/integrations/python.md)