> ## Documentation Index > Fetch the complete documentation index at: https://docs.paytring.com/llms.txt > Use this file to discover all available pages before exploring further. # Classify > Ask up to four typed questions about any state in one request. `POST https://ai.paytring.com/v1/classify/` Ask typed questions about a state and get structured decisions with probabilities back. **Authentication:** HTTP Basic using your Paytring credentials. Contact your **Paytring account manager** to get access. ```bash theme={null} curl -u "$PAYTRING_KEY:$PAYTRING_SECRET" https://ai.paytring.com/v1/classify/ ... ``` ### Request Body ```json theme={null} { "state": "any text, or a JSON object", // The document to decide about "questions": { // 1 to 4 questions "id": { "type": "choice | score | noul", // Question type "instructions": "what to decide", // Plain-language question "criteria": "options, levels, or omitted for noul" } } } ``` | Field | Type | Notes | | ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `state` | string, object, or array | Objects are serialized as JSON and read together with the questions. Arrays are treated as conversation turns. | | `questions` | object | 1–4 entries. The key becomes the answer key in the response. | | `type` | string | `choice`, `score`, or `noul`. | | `criteria` | object or array | `choice`: map of label to description (or list of labels), 1–20. `score`: ordered list of level descriptions, 2–20. `noul`: optional map with `false` and `true` descriptions. | ### Example: choice ```bash theme={null} curl -u "$PAYTRING_KEY:$PAYTRING_SECRET" https://ai.paytring.com/v1/classify/ \ -H 'content-type: application/json' \ -d '{ "state": { "subject": "Duplicate charge on invoice #4411", "body": "We were billed twice for March. Please refund the duplicate today or we will cancel our plan." }, "questions": { "department": { "type": "choice", "instructions": "Which department should handle this request?", "criteria": { "billing": "invoices, payments, refunds", "technical": "bugs, outages, system errors", "sales": "pricing, new contracts", "other": "everything else" } } } }' ``` ```json theme={null} { "model": "beep", "answers": { "department": { "type": "choice", "confidence": 0.8139, "choice": "billing", "probabilities": { "billing": 0.9487, "technical": 0.0156, "sales": 0.021, "other": 0.0147 } } }, "usage": { "input_tokens": 83, "output_tokens": 0 } } ``` ### Example: score ```bash theme={null} curl -u "$PAYTRING_KEY:$PAYTRING_SECRET" https://ai.paytring.com/v1/classify/ \ -H 'content-type: application/json' \ -d '{ "state": "The API returns error 503. Our entire production service is down.", "questions": { "urgency": { "type": "score", "instructions": "How urgent is this request?", "criteria": ["not urgent", "soon", "critical deadline or blocking issue"] } } }' ``` ```json theme={null} { "answers": { "urgency": { "type": "score", "confidence": 0.8555, "score": 1.9618, "legend": { "0": "not urgent", "1": "soon", "2": "critical deadline or blocking issue" }, "probabilities": { "0": 0.0055, "1": 0.0272, "2": 0.9673 } } }, "usage": { "input_tokens": 46, "output_tokens": 0 } } ``` ### Example: all three types in one call ```bash theme={null} curl -u "$PAYTRING_KEY:$PAYTRING_SECRET" https://ai.paytring.com/v1/classify/ \ -H 'content-type: application/json' \ -d '{ "state": { "subject": "Duplicate charge on invoice #4411", "body": "We were billed twice for March. Please refund the duplicate today or we will cancel our plan." }, "questions": { "department": { "type": "choice", "instructions": "Which department should handle this request?", "criteria": { "billing": "invoices, payments, refunds", "technical": "bugs, outages, system errors", "sales": "pricing, new contracts", "other": "everything else" } }, "urgency": { "type": "score", "instructions": "How urgent is this request?", "criteria": ["not urgent", "soon", "critical deadline or blocking issue"] }, "churn_risk": { "type": "noul", "instructions": "Does the user threaten to cancel or leave?" }, "refund_requested": { "type": "noul", "instructions": "Does the user explicitly request a refund?" } } }' ``` ```json theme={null} { "answers": { "department": { "type": "choice", "choice": "billing", "confidence": 0.8139, "probabilities": { "billing": 0.9487, "technical": 0.0156, "sales": 0.021, "other": 0.0147 } }, "urgency": { "type": "score", "score": 1.4892, "confidence": 0.1784, "legend": { "0": "not urgent", "1": "soon", "2": "critical deadline or blocking issue" }, "probabilities": { "0": 0.0954, "1": 0.32, "2": 0.5846 } }, "churn_risk": { "type": "noul", "noul": 0.7412, "confidence": 0.7412 }, "refund_requested": { "type": "noul", "noul": 0.8132, "confidence": 0.8132 } }, "usage": { "input_tokens": 296, "output_tokens": 0 } } ``` ### Responses #### 200 OK Every requested question appears under `answers`, keyed exactly as in your request. | Field | Notes | | -------------------- | ------------------------------------------------------------------------------------------------ | | `choice` | Winning label. `probabilities` covers all provided labels. | | `score` | Expected level (weighted by the distribution). `legend` maps indices to your level descriptions. | | `noul` | Probability, 0 to 1, that the statement holds. | | `confidence` | 0 to 1; higher means the distribution is more concentrated on the reported answer. | | `usage.input_tokens` | Tokens read for this request. | #### Errors | Status | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------------------- | | `401` | Missing or invalid credentials. | | `413` | Request body exceeds 32 KiB. | | `422` | Invalid input: missing `state`, unknown question type, malformed criteria, more than 4 questions, or more than 20 options. | | `429` | Too many requests; retry with backoff. | | `5xx` | Temporary failure. The call has no side effects, so retrying is safe. | ### Limits * 1–4 questions per request, up to 20 options per `choice` question. * 32 KiB request body. * Answer values are model decisions with probabilities. Validate confidence thresholds on your own data before automating decisions. Samples above are captured from the hosted model and may vary slightly per call.