{ "openapi": "3.1.0", "info": { "title": "Prismlet API", "version": "1.0.0", "description": "Prismlet answers typed questions about a text. A prism is a named set of fields, optional context and questions, built and versioned in the Prismlet app. Send a text to a prism and the answers come back in the same response. Every answered call is saved as a result, which you can read again by its id, and retry if it failed.\n\nResponses are snake_case JSON by default, with one answer per column of the prism's Lens. `format` switches to the stored answers, or to the result as a CSV, TSV or JSON Lines row." }, "servers": [ { "url": "https://api.prismlet.com/v1", "description": "Production. Not live yet." }, { "url": "http://localhost:2202/v1", "description": "Local development server, for Prismlet engineers." } ], "security": [{ "api_key": [] }], "tags": [{ "name": "Results" }], "components": { "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer", "bearerFormat": "pl_ followed by 32 characters", "description": "An account API key, sent as `Authorization: Bearer pl_...`. Create one on the API keys page of the app; the full key is shown once. A key works for every prism in its account.\n\nNo header, or one that is not `Bearer `, answers 401 `Authentication required`. `Bearer` is case-sensitive. A key that does not start with `pl_`, is unknown or was revoked answers 401 `Invalid API key`. A revoked key stops working on its next request." } }, "schemas": { "Format": { "type": "string", "enum": ["json", "raw", "csv", "tsv", "jsonl"], "default": "json" }, "ResultId": { "type": "string", "format": "uuid" }, "LensValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "One Lens column's value. What it holds depends on the column's output:\n\n- Choice `top`: the option key, `other` or `insufficient_information`. Null when the model named an option the prism does not have.\n- Choice `probability`: the chosen option's probability, from 0 to 1. Null when `top` is null.\n- Scale `probability`: the most probable level's probability, from 0 to 1.\n- Choice or Scale `all`: every option's probability, keyed by option key.\n- Yes / No `label`: `yes`, `no` or `unsure`, from the column's cutoffs.\n- Yes / No `probability`: the probability of yes, from 0 to 1.\n- Scale `level`: the most probable level's key.\n- Scale `number`: that level's position, 1 for the lowest.\n- Scale `average`: the expected level number, rounded to two decimals.\n\nNull for every output when the prism version that made the result has no such question, or has it as another type." }, "Result": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The result id. Use it to read or retry the result." }, "ref": { "type": ["string", "null"], "description": "The `ref` sent with the call, or null." }, "prism": { "type": "string", "description": "The prism's slug." }, "version": { "type": "integer", "minimum": 1, "description": "The prism version that answered." }, "status": { "type": "string", "enum": ["ok", "failed"], "description": "`ok`, or `failed` when the model gave no usable answer." }, "error": { "type": ["string", "null"], "description": "Why the result failed, in words. Null when `status` is `ok`." }, "took_ms": { "type": "integer", "minimum": 0, "description": "How long the call to the model took, in milliseconds." }, "created_at": { "type": "string", "format": "date-time", "description": "When the result was saved, ISO 8601 in UTC." }, "answers": { "type": ["object", "null"], "additionalProperties": { "$ref": "#/components/schemas/LensValue" }, "description": "One entry per column of the prism's Lens, keyed by column name, in Lens order. Null when the result failed." } }, "required": [ "id", "ref", "prism", "version", "status", "error", "took_ms", "created_at", "answers" ], "description": "A result in the default `json` format. `answers` is shaped by the prism's current Lens, so editing the Lens changes what an old result returns.", "title": "Result (json)" }, "ChoiceAnswer": { "type": "object", "properties": { "type": { "type": "string", "enum": ["choice"] }, "value": { "type": ["string", "null"], "description": "The chosen option key, `other` or `insufficient_information`. Null when the model named an option the prism does not have." }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Probability per option key, including `other` and `insufficient_information`, in no particular order." }, "confidence": { "type": "number", "description": "The model's confidence in the choice." } }, "required": ["type", "value", "probabilities", "confidence"], "description": "The answer to a Choice question." }, "YesNoAnswer": { "type": "object", "properties": { "type": { "type": "string", "enum": ["yes_no"] }, "probability": { "type": "number", "description": "The probability of yes, from 0 to 1." } }, "required": ["type", "probability"], "description": "The answer to a Yes / No question. Labels come from the Lens, not from here." }, "ScaleAnswer": { "type": "object", "properties": { "type": { "type": "string", "enum": ["scale"] }, "level": { "type": "string", "description": "The most probable level's key. On a tie the lower level wins." }, "probabilities": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Probability per level key. The keys come in no particular order; the prism lists its levels lowest first." } }, "required": ["type", "level", "probabilities"], "description": "The answer to a Scale question." }, "Answer": { "oneOf": [ { "$ref": "#/components/schemas/ChoiceAnswer" }, { "$ref": "#/components/schemas/YesNoAnswer" }, { "$ref": "#/components/schemas/ScaleAnswer" } ], "discriminator": { "propertyName": "type", "mapping": { "choice": "#/components/schemas/ChoiceAnswer", "yes_no": "#/components/schemas/YesNoAnswer", "scale": "#/components/schemas/ScaleAnswer" } }, "description": "The stored answer to one question." }, "RawResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The result id. Use it to read or retry the result." }, "ref": { "type": ["string", "null"], "description": "The `ref` sent with the call, or null." }, "prism": { "type": "string", "description": "The prism's slug." }, "version": { "type": "integer", "minimum": 1, "description": "The prism version that answered." }, "status": { "type": "string", "enum": ["ok", "failed"], "description": "`ok`, or `failed` when the model gave no usable answer." }, "error": { "type": ["string", "null"], "description": "Why the result failed, in words. Null when `status` is `ok`." }, "took_ms": { "type": "integer", "minimum": 0, "description": "How long the call to the model took, in milliseconds." }, "created_at": { "type": "string", "format": "date-time", "description": "When the result was saved, ISO 8601 in UTC." }, "answers": { "type": ["object", "null"], "additionalProperties": { "$ref": "#/components/schemas/Answer" }, "description": "The stored answer to every question, keyed by question key. Null when the result failed." } }, "required": [ "id", "ref", "prism", "version", "status", "error", "took_ms", "created_at", "answers" ], "description": "A result in `raw` format, with the stored answers and every probability. Lens edits never change it.", "title": "RawResult (raw)" }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "`validation_failed`, `bad_request`, `unauthorized`, `not_found`, `conflict` or `internal_error`." }, "message": { "type": "string", "description": "What went wrong, in words. A validation message names the failing paths and never repeats a value sent. `Unknown fields` lists the keys sent." } }, "required": ["code", "message"] } }, "required": ["error"], "description": "Every error has this body, in JSON, whatever `format` asked for." }, "CreateResultRequest": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 100000 }, "description": "One value per field of the prism version, keyed by field key. Every key the version declares is required and no other key is accepted. Each value is at most 100,000 characters. Together with the prism's context, the call's `context` and the longest question, the fields must fit an estimated 26,000 tokens, at four characters per token." }, "text": { "type": "string", "maxLength": 100000, "description": "Shorthand for `{\"fields\": {\"text\": \"...\"}}`, accepted by a prism whose only field is `text`." }, "context": { "type": "string", "maxLength": 100000, "description": "Background for this call only, such as the client's billing guideline or policy. The model reads the prism's context first, then a line `Context for this call:`, then this text. An empty or blank value is the same as leaving it out. At most 100,000 characters, and it counts toward the same token budget as the fields. It is saved with the result but not returned in any response or row." }, "ref": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Your own reference for the text, such as a ticket id. Returned with the result and in every row. It does not have to be unique. Leading and trailing whitespace is trimmed." }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "The prism version to answer with. Defaults to the latest saved version." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Makes the call safe to repeat. Unique within the account, shared by API and app calls. Leading and trailing whitespace is trimmed." } }, "description": "Send exactly one of `fields` and `text`.", "oneOf": [ { "title": "fields", "required": ["fields"] }, { "title": "text shorthand", "required": ["text"] } ] } }, "parameters": { "Format": { "schema": { "$ref": "#/components/schemas/Format" }, "required": false, "description": "What the response body holds.\n\n- `json`: the result, with `answers` shaped by the prism's Lens.\n- `raw`: the result, with the stored answers and every probability.\n- `csv`, `tsv`: a header row and one row for the result.\n- `jsonl`: one line holding the same row as a JSON object.\n\nDefaults to `json`, also when sent empty. An unknown value answers 400. Errors are JSON in every format.", "name": "format", "in": "query" }, "ResultId": { "schema": { "$ref": "#/components/schemas/ResultId" }, "required": true, "description": "The result's `id`.", "name": "result_id", "in": "path", "example": "0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c" } } }, "paths": { "/prisms/{prism}/results": { "post": { "operationId": "createResult", "tags": ["Results"], "summary": "Answer one text", "description": "Runs the prism on one text and waits for the answers. The response is the saved result, so there is nothing to poll. One call answers one text; for many texts, make one call each.\n\nSend `fields` with exactly the field keys of the prism version. A prism whose only field is `text` also takes `{\"text\": \"...\"}`. The latest saved version answers unless `version` names another. An archived prism answers 404.\n\nWith `idempotency_key` the call is safe to repeat. If a stored result already holds the key and succeeded, it comes back without calling the model, whatever the rest of the body says. If that result failed, the same key retries it and moves to the new result. A key first used with another prism answers 409. Two first calls with the same key at the same moment may both be sent to the model, but only one result is saved and both calls get it.\n\nWhen the model fails, the failed result is saved and returned on 502, in the format asked for. Each attempt to reach the model times out after 15 seconds by default. A 429 or 5xx from the model service gets one more attempt, and a timeout or a network error fails the call at once, so allow at least 30 seconds before giving up on a call.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true, "description": "The prism's slug or its id. The slug is set when the prism is created and does not follow renames. A value shaped like a UUID is read as the id. An unknown or archived prism answers 404.", "example": "support-routing", "name": "prism", "in": "path" }, { "$ref": "#/components/parameters/Format" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResultRequest" }, "examples": { "fields": { "summary": "Fields, with a reference and an idempotency key", "value": { "ref": "TCK-8812", "fields": { "subject": "Charged twice this month", "text": "Hi, I was billed twice for September. Please refund the second charge before Friday." }, "idempotency_key": "tck-8812-1" } }, "text": { "summary": "The text shorthand, for a prism whose only field is text", "value": { "text": "Hi, I was billed twice for September. Please refund the second charge before Friday." } } } } } }, "responses": { "200": { "description": "The text was answered and saved, or the idempotency key matched a stored result that succeeded.", "content": { "application/json; charset=utf-8": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/RawResult" } ], "description": "A `Result` for `format=json` (the default), a `RawResult` for `raw`." }, "examples": { "json": { "summary": "Answered, format=json", "value": { "id": "0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:14:02.187Z", "answers": { "team": "billing", "team_probability": 0.91, "urgent": "yes", "tone": "annoyed", "tone_average": 2.05 } } }, "raw": { "summary": "Answered, format=raw", "value": { "id": "0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:14:02.187Z", "answers": { "team": { "type": "choice", "value": "billing", "probabilities": { "billing": 0.91, "technical": 0.05, "other": 0.03, "insufficient_information": 0.01 }, "confidence": 0.88 }, "urgent": { "type": "yes_no", "probability": 0.83 }, "tone": { "type": "scale", "level": "annoyed", "probabilities": { "calm": 0.12, "annoyed": 0.71, "angry": 0.17 } } } } } } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "A header row, then one row. The columns are `result_id`, `ref`, `version`, `status`, `error`, `created_at`, one per field of the latest prism version, then the Lens columns. Cells hold option labels and Yes, No or Unsure. Lines end in CRLF. A cell holding a comma, a quote or a line break is quoted, with quotes doubled. An empty value is an empty cell." }, "examples": { "csv": { "summary": "Answered, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c,TCK-8812,3,ok,,2026-09-23T09:14:02.187Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",Billing,0.91,Yes,Annoyed,2.05\r\n" } } }, "text/tab-separated-values; charset=utf-8": { "schema": { "type": "string", "description": "The `csv` columns, separated by tabs, with lines ending in LF. Tabs and line breaks inside a cell become spaces." }, "examples": { "tsv": { "summary": "Answered, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c\tTCK-8812\t3\tok\t\t2026-09-23T09:14:02.187Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\tBilling\t0.91\tYes\tAnnoyed\t2.05\n" } } }, "application/x-ndjson; charset=utf-8": { "schema": { "type": "string", "description": "One line ending in LF, holding the `csv` row as a JSON object, with option keys and `yes`, `no` or `unsure` instead of labels, and `all` columns as objects." }, "examples": { "jsonl": { "summary": "Answered, format=jsonl", "value": "{\"result_id\":\"0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"ok\",\"error\":null,\"created_at\":\"2026-09-23T09:14:02.187Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":\"billing\",\"team_probability\":0.91,\"urgent\":\"yes\",\"tone\":\"annoyed\",\"tone_average\":2.05}\n" } } } } }, "400": { "description": "The request is invalid. Nothing was sent to the model and nothing was saved.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_field": { "summary": "Missing field", "value": { "error": { "code": "validation_failed", "message": "Missing fields: subject" } } }, "unknown_field": { "summary": "Unknown field", "value": { "error": { "code": "validation_failed", "message": "Unknown fields: body" } } }, "both_fields_and_text": { "summary": "Both fields and text", "value": { "error": { "code": "validation_failed", "message": "Invalid request: fields: send either fields or text" } } }, "field_too_long": { "summary": "Field too long", "value": { "error": { "code": "validation_failed", "message": "Invalid request: fields.text: String must contain at most 100000 character(s)" } } }, "over_the_token_budget": { "summary": "Over the token budget", "value": { "error": { "code": "validation_failed", "message": "Request too large: about 27100 tokens of fields, context and the longest question, the limit is 26000" } } }, "unknown_format": { "summary": "Unknown format", "value": { "error": { "code": "validation_failed", "message": "Invalid request: format: Expected 'json' | 'raw' | 'csv' | 'tsv' | 'jsonl'" } } }, "body_is_not_valid_json": { "summary": "Body is not valid JSON", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "401": { "description": "No API key, or one that is unknown or revoked.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_authorization_header": { "summary": "No Authorization header", "value": { "error": { "code": "unauthorized", "message": "Authentication required" } } }, "unknown_or_revoked_key": { "summary": "Unknown or revoked key", "value": { "error": { "code": "unauthorized", "message": "Invalid API key" } } } } } } }, "404": { "description": "The prism does not exist in this account or is archived, or the version does not exist.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unknown_or_archived_prism": { "summary": "Unknown or archived prism", "value": { "error": { "code": "not_found", "message": "Prism not found" } } }, "unknown_version": { "summary": "Unknown version", "value": { "error": { "code": "not_found", "message": "Prism version not found" } } } } } } }, "409": { "description": "The idempotency key was first used with another prism. When two first calls race with one key and different prisms, the one that loses gets this after its text was sent to the model.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "key_used_for_another_prism": { "summary": "Key used for another prism", "value": { "error": { "code": "conflict", "message": "This idempotency key was already used for another prism." } } } } } } }, "413": { "description": "The body is over 1 MiB.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "body_too_large": { "summary": "Body too large", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "415": { "description": "The body has a content type the server does not parse. Send `application/json`.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_content_type": { "summary": "Unsupported content type", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "500": { "description": "A bug on our side. The message is always the same.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "value": { "error": { "code": "internal_error", "message": "Internal server error" } } } } } } }, "502": { "description": "The model failed. The failed result is saved and returned with `status` set to `failed`, `answers` null and the error. Retry it, or repeat the call with the same idempotency key.", "content": { "application/json; charset=utf-8": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/RawResult" } ], "description": "A `Result` for `format=json` (the default), a `RawResult` for `raw`." }, "examples": { "json": { "summary": "Model timed out, format=json", "value": { "id": "0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:15:40.502Z", "answers": null } }, "raw": { "summary": "Model timed out, format=raw", "value": { "id": "0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:15:40.502Z", "answers": null } } } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "A header row, then one row. The columns are `result_id`, `ref`, `version`, `status`, `error`, `created_at`, one per field of the latest prism version, then the Lens columns. Cells hold option labels and Yes, No or Unsure. Lines end in CRLF. A cell holding a comma, a quote or a line break is quoted, with quotes doubled. An empty value is an empty cell." }, "examples": { "csv": { "summary": "Model timed out, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13,TCK-8812,3,failed,\"The model took too long to answer, so we stopped after 15 seconds.\",2026-09-23T09:15:40.502Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",,,,,\r\n" } } }, "text/tab-separated-values; charset=utf-8": { "schema": { "type": "string", "description": "The `csv` columns, separated by tabs, with lines ending in LF. Tabs and line breaks inside a cell become spaces." }, "examples": { "tsv": { "summary": "Model timed out, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13\tTCK-8812\t3\tfailed\tThe model took too long to answer, so we stopped after 15 seconds.\t2026-09-23T09:15:40.502Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\t\t\t\t\t\n" } } }, "application/x-ndjson; charset=utf-8": { "schema": { "type": "string", "description": "One line ending in LF, holding the `csv` row as a JSON object, with option keys and `yes`, `no` or `unsure` instead of labels, and `all` columns as objects." }, "examples": { "jsonl": { "summary": "Model timed out, format=jsonl", "value": "{\"result_id\":\"0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"failed\",\"error\":\"The model took too long to answer, so we stopped after 15 seconds.\",\"created_at\":\"2026-09-23T09:15:40.502Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":null,\"team_probability\":null,\"urgent\":null,\"tone\":null,\"tone_average\":null}\n" } } } } } } } }, "/results/{result_id}": { "get": { "operationId": "getResult", "tags": ["Results"], "summary": "Read a result", "description": "Returns a saved result from this account, whether the API, the app or a file run made it. Nothing is sent to the model.\n\n`json` applies the prism's current Lens to the stored answers, so a Lens edit changes what an old result returns. `raw` returns the stored answers and never changes. A failed result answers 200 too, with `status` set to `failed`. Results of an archived prism stay readable.", "parameters": [ { "$ref": "#/components/parameters/ResultId" }, { "$ref": "#/components/parameters/Format" } ], "responses": { "200": { "description": "The result, whether it succeeded or failed.", "content": { "application/json; charset=utf-8": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/RawResult" } ], "description": "A `Result` for `format=json` (the default), a `RawResult` for `raw`." }, "examples": { "json_answered": { "summary": "Answered, format=json", "value": { "id": "0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:14:02.187Z", "answers": { "team": "billing", "team_probability": 0.91, "urgent": "yes", "tone": "annoyed", "tone_average": 2.05 } } }, "json_failed": { "summary": "Failed, format=json", "value": { "id": "0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:15:40.502Z", "answers": null } }, "raw_answered": { "summary": "Answered, format=raw", "value": { "id": "0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:14:02.187Z", "answers": { "team": { "type": "choice", "value": "billing", "probabilities": { "billing": 0.91, "technical": 0.05, "other": 0.03, "insufficient_information": 0.01 }, "confidence": 0.88 }, "urgent": { "type": "yes_no", "probability": 0.83 }, "tone": { "type": "scale", "level": "annoyed", "probabilities": { "calm": 0.12, "annoyed": 0.71, "angry": 0.17 } } } } }, "raw_failed": { "summary": "Failed, format=raw", "value": { "id": "0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:15:40.502Z", "answers": null } } } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "A header row, then one row. The columns are `result_id`, `ref`, `version`, `status`, `error`, `created_at`, one per field of the latest prism version, then the Lens columns. Cells hold option labels and Yes, No or Unsure. Lines end in CRLF. A cell holding a comma, a quote or a line break is quoted, with quotes doubled. An empty value is an empty cell." }, "examples": { "csv_answered": { "summary": "Answered, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c,TCK-8812,3,ok,,2026-09-23T09:14:02.187Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",Billing,0.91,Yes,Annoyed,2.05\r\n" }, "csv_failed": { "summary": "Failed, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13,TCK-8812,3,failed,\"The model took too long to answer, so we stopped after 15 seconds.\",2026-09-23T09:15:40.502Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",,,,,\r\n" } } }, "text/tab-separated-values; charset=utf-8": { "schema": { "type": "string", "description": "The `csv` columns, separated by tabs, with lines ending in LF. Tabs and line breaks inside a cell become spaces." }, "examples": { "tsv_answered": { "summary": "Answered, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c\tTCK-8812\t3\tok\t\t2026-09-23T09:14:02.187Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\tBilling\t0.91\tYes\tAnnoyed\t2.05\n" }, "tsv_failed": { "summary": "Failed, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13\tTCK-8812\t3\tfailed\tThe model took too long to answer, so we stopped after 15 seconds.\t2026-09-23T09:15:40.502Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\t\t\t\t\t\n" } } }, "application/x-ndjson; charset=utf-8": { "schema": { "type": "string", "description": "One line ending in LF, holding the `csv` row as a JSON object, with option keys and `yes`, `no` or `unsure` instead of labels, and `all` columns as objects." }, "examples": { "jsonl_answered": { "summary": "Answered, format=jsonl", "value": "{\"result_id\":\"0192f5c1-7c1a-7b3e-9f55-3c1d2e4a5b6c\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"ok\",\"error\":null,\"created_at\":\"2026-09-23T09:14:02.187Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":\"billing\",\"team_probability\":0.91,\"urgent\":\"yes\",\"tone\":\"annoyed\",\"tone_average\":2.05}\n" }, "jsonl_failed": { "summary": "Failed, format=jsonl", "value": "{\"result_id\":\"0192f5c3-2b4e-7d10-8a61-5e0f9c7d2a13\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"failed\",\"error\":\"The model took too long to answer, so we stopped after 15 seconds.\",\"created_at\":\"2026-09-23T09:15:40.502Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":null,\"team_probability\":null,\"urgent\":null,\"tone\":null,\"tone_average\":null}\n" } } } } }, "400": { "description": "The result id or the format is invalid.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "result_id_is_not_a_uuid": { "summary": "Result id is not a UUID", "value": { "error": { "code": "validation_failed", "message": "Invalid request: result_id: Invalid uuid" } } }, "unknown_format": { "summary": "Unknown format", "value": { "error": { "code": "validation_failed", "message": "Invalid request: format: Expected 'json' | 'raw' | 'csv' | 'tsv' | 'jsonl'" } } } } } } }, "401": { "description": "No API key, or one that is unknown or revoked.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_authorization_header": { "summary": "No Authorization header", "value": { "error": { "code": "unauthorized", "message": "Authentication required" } } }, "unknown_or_revoked_key": { "summary": "Unknown or revoked key", "value": { "error": { "code": "unauthorized", "message": "Invalid API key" } } } } } } }, "404": { "description": "No result with this id in this account.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unknown_result": { "summary": "Unknown result", "value": { "error": { "code": "not_found", "message": "Result not found" } } } } } } }, "500": { "description": "A bug on our side. The message is always the same.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "value": { "error": { "code": "internal_error", "message": "Internal server error" } } } } } } } } } }, "/results/{result_id}/retry": { "post": { "operationId": "retryResult", "tags": ["Results"], "summary": "Retry a failed result", "description": "Sends a failed result's fields to the model again, against the same prism version, and saves the answer as a new result with its own id. The response is that new result, on 200 or 502. Send no body.\n\nOnly a failed result can be retried, and only once. A second retry answers 409 and names the result that retried it. If that retry failed too, retry it in turn. An idempotency key held by the failed result moves to the new one. A result of an archived prism cannot be retried and answers 404.", "parameters": [ { "$ref": "#/components/parameters/ResultId" }, { "$ref": "#/components/parameters/Format" } ], "responses": { "200": { "description": "The retry was answered and saved as a new result.", "content": { "application/json; charset=utf-8": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/RawResult" } ], "description": "A `Result` for `format=json` (the default), a `RawResult` for `raw`." }, "examples": { "json": { "summary": "Answered on retry, format=json", "value": { "id": "0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:16:05.931Z", "answers": { "team": "billing", "team_probability": 0.91, "urgent": "yes", "tone": "annoyed", "tone_average": 2.05 } } }, "raw": { "summary": "Answered on retry, format=raw", "value": { "id": "0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "ok", "error": null, "took_ms": 640, "created_at": "2026-09-23T09:16:05.931Z", "answers": { "team": { "type": "choice", "value": "billing", "probabilities": { "billing": 0.91, "technical": 0.05, "other": 0.03, "insufficient_information": 0.01 }, "confidence": 0.88 }, "urgent": { "type": "yes_no", "probability": 0.83 }, "tone": { "type": "scale", "level": "annoyed", "probabilities": { "calm": 0.12, "annoyed": 0.71, "angry": 0.17 } } } } } } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "A header row, then one row. The columns are `result_id`, `ref`, `version`, `status`, `error`, `created_at`, one per field of the latest prism version, then the Lens columns. Cells hold option labels and Yes, No or Unsure. Lines end in CRLF. A cell holding a comma, a quote or a line break is quoted, with quotes doubled. An empty value is an empty cell." }, "examples": { "csv": { "summary": "Answered on retry, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2,TCK-8812,3,ok,,2026-09-23T09:16:05.931Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",Billing,0.91,Yes,Annoyed,2.05\r\n" } } }, "text/tab-separated-values; charset=utf-8": { "schema": { "type": "string", "description": "The `csv` columns, separated by tabs, with lines ending in LF. Tabs and line breaks inside a cell become spaces." }, "examples": { "tsv": { "summary": "Answered on retry, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2\tTCK-8812\t3\tok\t\t2026-09-23T09:16:05.931Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\tBilling\t0.91\tYes\tAnnoyed\t2.05\n" } } }, "application/x-ndjson; charset=utf-8": { "schema": { "type": "string", "description": "One line ending in LF, holding the `csv` row as a JSON object, with option keys and `yes`, `no` or `unsure` instead of labels, and `all` columns as objects." }, "examples": { "jsonl": { "summary": "Answered on retry, format=jsonl", "value": "{\"result_id\":\"0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"ok\",\"error\":null,\"created_at\":\"2026-09-23T09:16:05.931Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":\"billing\",\"team_probability\":0.91,\"urgent\":\"yes\",\"tone\":\"annoyed\",\"tone_average\":2.05}\n" } } } } }, "400": { "description": "The result id or the format is invalid, or the body is not valid JSON.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "result_id_is_not_a_uuid": { "summary": "Result id is not a UUID", "value": { "error": { "code": "validation_failed", "message": "Invalid request: result_id: Invalid uuid" } } }, "unknown_format": { "summary": "Unknown format", "value": { "error": { "code": "validation_failed", "message": "Invalid request: format: Expected 'json' | 'raw' | 'csv' | 'tsv' | 'jsonl'" } } }, "body_is_not_valid_json": { "summary": "Body is not valid JSON", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "401": { "description": "No API key, or one that is unknown or revoked.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "no_authorization_header": { "summary": "No Authorization header", "value": { "error": { "code": "unauthorized", "message": "Authentication required" } } }, "unknown_or_revoked_key": { "summary": "Unknown or revoked key", "value": { "error": { "code": "unauthorized", "message": "Invalid API key" } } } } } } }, "404": { "description": "No result with this id in this account, or its prism is archived.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unknown_result": { "summary": "Unknown result", "value": { "error": { "code": "not_found", "message": "Result not found" } } }, "archived_prism": { "summary": "Archived prism", "value": { "error": { "code": "not_found", "message": "This prism is archived, so it cannot answer." } } } } } } }, "409": { "description": "The result succeeded, or it was already retried.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "result_succeeded": { "summary": "Result succeeded", "value": { "error": { "code": "conflict", "message": "Only a failed result can be retried." } } }, "already_retried": { "summary": "Already retried", "value": { "error": { "code": "conflict", "message": "This result was already retried as 0192f5c4-9e27-7c55-b3d8-41a6f0e8c9b2." } } } } } } }, "413": { "description": "A body over 1 MiB was sent. Send no body.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "body_too_large": { "summary": "Body too large", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "415": { "description": "A body was sent with a content type the server does not parse. Send no body.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unsupported_content_type": { "summary": "Unsupported content type", "value": { "error": { "code": "bad_request", "message": "Malformed request" } } } } } } }, "500": { "description": "A bug on our side. The message is always the same.", "content": { "application/json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unexpected_error": { "summary": "Unexpected error", "value": { "error": { "code": "internal_error", "message": "Internal server error" } } } } } } }, "502": { "description": "The model failed again. The new failed result is saved and returned, and can be retried in turn.", "content": { "application/json; charset=utf-8": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Result" }, { "$ref": "#/components/schemas/RawResult" } ], "description": "A `Result` for `format=json` (the default), a `RawResult` for `raw`." }, "examples": { "json": { "summary": "Model timed out again, format=json", "value": { "id": "0192f5c5-4d81-7a02-9c3e-6b27d1f0a845", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:16:38.644Z", "answers": null } }, "raw": { "summary": "Model timed out again, format=raw", "value": { "id": "0192f5c5-4d81-7a02-9c3e-6b27d1f0a845", "ref": "TCK-8812", "prism": "support-routing", "version": 3, "status": "failed", "error": "The model took too long to answer, so we stopped after 15 seconds.", "took_ms": 15012, "created_at": "2026-09-23T09:16:38.644Z", "answers": null } } } }, "text/csv; charset=utf-8": { "schema": { "type": "string", "description": "A header row, then one row. The columns are `result_id`, `ref`, `version`, `status`, `error`, `created_at`, one per field of the latest prism version, then the Lens columns. Cells hold option labels and Yes, No or Unsure. Lines end in CRLF. A cell holding a comma, a quote or a line break is quoted, with quotes doubled. An empty value is an empty cell." }, "examples": { "csv": { "summary": "Model timed out again, format=csv", "value": "result_id,ref,version,status,error,created_at,subject,text,team,team_probability,urgent,tone,tone_average\r\n0192f5c5-4d81-7a02-9c3e-6b27d1f0a845,TCK-8812,3,failed,\"The model took too long to answer, so we stopped after 15 seconds.\",2026-09-23T09:16:38.644Z,Charged twice this month,\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",,,,,\r\n" } } }, "text/tab-separated-values; charset=utf-8": { "schema": { "type": "string", "description": "The `csv` columns, separated by tabs, with lines ending in LF. Tabs and line breaks inside a cell become spaces." }, "examples": { "tsv": { "summary": "Model timed out again, format=tsv", "value": "result_id\tref\tversion\tstatus\terror\tcreated_at\tsubject\ttext\tteam\tteam_probability\turgent\ttone\ttone_average\n0192f5c5-4d81-7a02-9c3e-6b27d1f0a845\tTCK-8812\t3\tfailed\tThe model took too long to answer, so we stopped after 15 seconds.\t2026-09-23T09:16:38.644Z\tCharged twice this month\tHi, I was billed twice for September. Please refund the second charge before Friday.\t\t\t\t\t\n" } } }, "application/x-ndjson; charset=utf-8": { "schema": { "type": "string", "description": "One line ending in LF, holding the `csv` row as a JSON object, with option keys and `yes`, `no` or `unsure` instead of labels, and `all` columns as objects." }, "examples": { "jsonl": { "summary": "Model timed out again, format=jsonl", "value": "{\"result_id\":\"0192f5c5-4d81-7a02-9c3e-6b27d1f0a845\",\"ref\":\"TCK-8812\",\"version\":3,\"status\":\"failed\",\"error\":\"The model took too long to answer, so we stopped after 15 seconds.\",\"created_at\":\"2026-09-23T09:16:38.644Z\",\"subject\":\"Charged twice this month\",\"text\":\"Hi, I was billed twice for September. Please refund the second charge before Friday.\",\"team\":null,\"team_probability\":null,\"urgent\":null,\"tone\":null,\"tone_average\":null}\n" } } } } } } } } } }