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.
curl -u "$PAYTRING_KEY:$PAYTRING_SECRET" https://ai.paytring.com/v1/classify/ ...
Request Body
{
"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
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"
}
}
}
}'
{
"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
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"]
}
}
}'
{
"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
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?"
}
}
}'
{
"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 underanswers, 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
choicequestion. - 32 KiB request body.
- Answer values are model decisions with probabilities. Validate confidence thresholds on your own data before automating decisions.