Prisms, fields and questions

A prism is a named set of fields, optional context and questions. You build and test it in the Prismlet app, and the API runs it on one text per call. Saving a prism creates its next version.

Naming a prism in a URL

The {prism} in /v1/prisms/{prism}/results is the prism's slug or its id.

• The slug is set from the name when the prism is created, such as support-routing for Support routing. Renaming the prism does not change it, so your URLs keep working.
• The id is a UUID. A value shaped like a UUID is always read as an id, which is why no slug can look like one.
• An archived prism answers 404 for new calls and retries. Its results stay readable.

Fields

A field is a named piece of text you send with each call. It has a key, such as subject, and a label, such as Subject, which the app shows.

• A prism has one to eight fields.
• A key is snake_case: a lowercase letter, then up to 63 lowercase letters, digits or underscores.
• context is reserved, and so are the row names result_id, ref, version, status, error and created_at.
• Once the prism is saved, a field's key is fixed, because your code sends it. To send a different key, add a new field and remove the old one.

Every call sends exactly the field keys of the prism version it runs against. A missing key and an extra key are both a 400. Sending a text has the details.

Context

Context is optional background that every question sees, such as "We sell scheduling software to clinics." It is part of the prism, holds up to 8,000 characters, and counts toward the size of every call. A call can add background of its own with context, which the model reads after the prism's.

Questions

A question is one judgment about the fields. It has a key, a type, the question text the app shows, and optional instructions. The model reads text first, then instructions when present, so instructions add detail to the question and need not repeat it. A prism has one to 100 questions, and question keys share one namespace with field keys. Once saved, a question keeps its key and its type, so your code always reads the same shape of answer under a key. For another key or type, add a new question. Saving a version that gives a question key from any earlier version a different type is refused with a 400.

There are three types.

Type	In the app	Asks for	Options	Stored answer
choice	Choice	One option from a list	2 to 253	value, probabilities per option, confidence
yes_no	Yes / No	The probability that it is yes	None	probability of yes, from 0 to 1
scale	Scale	One level of an ordered list	2 to 10, lowest first	level, probabilities per level

Options and levels have a key, a label and an optional description. The description is what the model reads to tell options apart, so write one whenever two options could be confused. The app derives an option key from its label. Once the option is saved, the key stays when you edit the label.

Choice

A Choice answers with one option key. Its stored answer has a probability for every option and the model's confidence in the choice.

Two more outcomes are always possible, and every Choice has them without you adding them:

Key	Label	Means
other	Other	None of the options fit the text.
insufficient_information	Not enough information	The text does not say enough to choose.

You can't use these keys for your own options. Handle both in your code. A router that only knows billing and technical needs a path for a ticket that is neither.

A Choice value is null when the model named an option the prism does not have. The app shows it as "No valid answer". It is not an error, and the result's status is still ok.

Yes / No

A Yes / No answer is only a probability. It has no stored label. The Lens turns the probability into yes, no or unsure with cutoffs you choose, and you can change them later without asking the model again. See Yes / No cutoffs.

Scale

A Scale has ordered levels, written lowest first, such as Calm, Annoyed, Angry. Its stored answer is the most probable level and a probability for every level. On a tie the lower level wins. The Lens can also return the level's position or the expected level number.

Versions

Saving a prism creates the next version, numbered from 1. A saved version never changes.

• Every save creates a new version, whether it changed the fields, the context, the questions, their options, the name or nothing at all.
• Editing the Lens is not a version.
• Calls use the latest version unless the body names another with version.
• Every result records the version that answered it.

Pin version when your code depends on a version's field keys, for example while someone adds a field in the app that your code does not send yet. An unknown version answers 404 with Prism version not found.