Skip to content
prismletAPI docs

Answer one text

POST
/prisms/{prism}/results
curl --request POST \
  --url 'https://api.prismlet.com/v1/prisms/support-routing/results?format=json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "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" }'

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.

Send 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.

With 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.

When 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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
prism
required
string
>= 1 characters <= 64 characters

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

Query Parameters

Section titled “Query Parameters”
format
string
default: json
Allowed values: json raw csv tsv jsonl

What the response body holds.

  • json: the result, with answers shaped by the prism’s Lens.
  • raw: the result, with the stored answers and every probability.
  • csv, tsv: a header row and one row for the result.
  • jsonl: one line holding the same row as a JSON object.

Defaults to json, also when sent empty. An unknown value answers 400. Errors are JSON in every format.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
fields

Send exactly one of fields and text.

object
fields
required

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.

object
key
additional properties
string
<= 100000 characters
text

Shorthand for {"fields": {"text": "..."}}, accepted by a prism whose only field is text.

string
<= 100000 characters
context

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.

string
<= 100000 characters
ref

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.

string
>= 1 characters <= 200 characters
version

The prism version to answer with. Defaults to the latest saved version.

integer
>= 1 <= 2147483647
idempotency_key

Makes the call safe to repeat. Unique within the account, shared by API and app calls. Leading and trailing whitespace is trimmed.

string
>= 1 characters <= 200 characters
Examples

Fields, with a reference and an idempotency key

{
  "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"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The text was answered and saved, or the idempotency key matched a stored result that succeeded.

Any of:
Result (json)

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.

object
id
required

The result id. Use it to read or retry the result.

string format: uuid
ref
required

The ref sent with the call, or null.

string | null
prism
required

The prism’s slug.

string
version
required

The prism version that answered.

integer
>= 1
status
required

ok, or failed when the model gave no usable answer.

string
Allowed values: ok failed
error
required

Why the result failed, in words. Null when status is ok.

string | null
took_ms
required

How long the call to the model took, in milliseconds.

integer
created_at
required

When the result was saved, ISO 8601 in UTC.

string format: date-time
answers
required

One entry per column of the prism’s Lens, keyed by column name, in Lens order. Null when the result failed.

object | null
Examples

Answered, format=json

{
  "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
  }
}

400

Section titled “400”

The request is invalid. Nothing was sent to the model and nothing was saved.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples

Missing field

{
  "error": {
    "code": "validation_failed",
    "message": "Missing fields: subject"
  }
}

401

Section titled “401”

No API key, or one that is unknown or revoked.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples

No Authorization header

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

404

Section titled “404”

The prism does not exist in this account or is archived, or the version does not exist.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples

Unknown or archived prism

{
  "error": {
    "code": "not_found",
    "message": "Prism not found"
  }
}

409

Section titled “409”

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.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples
Examplekey_used_for_another_prism

Key used for another prism

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key was already used for another prism."
  }
}

413

Section titled “413”

The body is over 1 MiB.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples
Examplebody_too_large

Body too large

{
  "error": {
    "code": "bad_request",
    "message": "Malformed request"
  }
}

415

Section titled “415”

The body has a content type the server does not parse. Send application/json.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples
Exampleunsupported_content_type

Unsupported content type

{
  "error": {
    "code": "bad_request",
    "message": "Malformed request"
  }
}

500

Section titled “500”

A bug on our side. The message is always the same.

Media typeapplication/json; charset=utf-8

Every error has this body, in JSON, whatever format asked for.

object
error
required
object
code
required

validation_failed, bad_request, unauthorized, not_found, conflict or internal_error.

string
message
required

What went wrong, in words. A validation message names the failing paths and never repeats a value sent. Unknown fields lists the keys sent.

string
Examples
Exampleunexpected_error

Unexpected error

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

502

Section titled “502”

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.

Any of:
Result (json)

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.

object
id
required

The result id. Use it to read or retry the result.

string format: uuid
ref
required

The ref sent with the call, or null.

string | null
prism
required

The prism’s slug.

string
version
required

The prism version that answered.

integer
>= 1
status
required

ok, or failed when the model gave no usable answer.

string
Allowed values: ok failed
error
required

Why the result failed, in words. Null when status is ok.

string | null
took_ms
required

How long the call to the model took, in milliseconds.

integer
created_at
required

When the result was saved, ISO 8601 in UTC.

string format: date-time
answers
required

One entry per column of the prism’s Lens, keyed by column name, in Lens order. Null when the result failed.

object | null
Examples

Model timed out, format=json

{
  "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
}