Use cases
Pea answers Choice, Noul and Score questions. We propose 11 APIs that add new functions to these questions. Each API has three use cases and a sample request.
Status: proposed. None of these APIs is available. The samples show a planned format, and the format can change. The numbers in the samples are examples, not measured results.
The proposed APIs
Select an API to see its use cases and a sample.
- 01 · POST /v1/predict · riskTarget error rateAnswer or abstain below an error rate that you set.
- 02 · POST /v1/alignmentsShow the evidenceFind the source sentences that support or contradict each claim.
- 03 · POST /v1/predict · estimateNumber with a rangeGet a quantity with a median and a range.
- 04 · POST /v1/annotateLabel every part of a documentAnswer questions for each part of a long document.
- 05 · POST /v1/states · /eventsWatch a conversationCheck standing questions after each new message.
- 06 · POST /v1/feedbackUse your correctionsUpdate your model version with your corrections.
- 07 · POST /v1/predict · givenIf so, then…Ask a question that assumes the answer to another question.
- 08 · POST /v1/predict · bindPick the correct recordPick a record from a list in the state.
- 09 · POST /v1/flowsStep-by-step checksDo a sequence of checks with an audit record.
- 10 · POST /v1/rankingsRank with probabilitiesGet the probability of rank 1 and of the top k.
- 11 · POST /v1/predict · effortSelect effortSelect the effort for each question.
Why new APIs
Jev and Pea return a probability for each outcome that you supply. Other vendors now sell the same three question types. Each proposed API adds a function that these calls cannot give, or can give only with many calls. Each section tells you the problem with Jev-style calls.
Proposed · Not available
1. Target error rate
POST /v1/predict · risk
You set a maximum error rate. Pea gives an answer when it estimates an error rate below that limit. If it cannot, it tells you to send the case to a person. The target holds for data like your calibration examples.
Problem with Jev-style calls. Jev gives a probability, for example 0.92. It does not tell you if 0.92 is below your error limit. You must calculate an error limit and calculate it again after each model update.
SOFTWARE ENGINEERING
Merge gate for API changes
A CI job asks if a pull request breaks the public API. The target is 5 errors in 100 answered cases. An answer that is not an abstain blocks or allows the merge. An abstain result assigns a reviewer.
CUSTOMER SUPPORT & E-COMMERCE
Refund email routes
A web shop sends each refund email to Pea. The target is 2 errors in 100 answered cases. Pea sends duplicate-charge emails to a fast queue. An agent makes each payout decision.
HEALTHCARE ADMINISTRATION
Admission type on a billing record
A billing system asks if a hospital stay is inpatient. The target is 2 errors in 100 answered cases. A medical coder checks each claim, and abstain results go to the top of the queue.
Sample: Merge gate for API changes. Before the first call, you send labelled examples to POST /v1/calibrations. You get the calibration ID.
REQUEST · POST /v1/predict
{
"state": {
"pull_request": "#4821: Rename an internal helper. Change the default page size of GET /users from 50 to 20.",
"changed_files": ["api/users.py", "openapi.yaml"]
},
"questions": {
"breaking": {
"type": "noul",
"statement": "This pull request breaks the public API.",
"risk": {
"max_error": 0.05,
"calibration": "cal_api_breaks_v2"
}
}
}
}
ILLUSTRATIVE RESPONSE
{
"answers": {
"breaking": {
"type": "noul",
"noul": 0.58,
"probabilities": {"true": 0.58, "false": 0.42},
"risk": {
"decision": "abstain",
"prediction_set": ["true", "false"],
"max_error": 0.05,
"calibration": "cal_api_breaks_v2"
}
}
}
}
Proposed · Not available
2. Show the evidence
POST /v1/alignments
Send a text and its sources. For each claim in the text, Pea shows the source sentences that support or contradict the claim, with their positions.
Problem with Jev-style calls. Jev needs one question for each claim and each source sentence. Ten claims and 200 source sentences make 2,000 questions. The answers do not show where the evidence is.
SOFTWARE ENGINEERING
Release notes against merged changes
A release tool sends the release notes and the titles of the merged pull requests. Pea shows the source of each claim. The tool marks each claim without support.
CUSTOMER SUPPORT & E-COMMERCE
Chatbot answers before you send them
A support bot writes an answer about returns. Pea compares each sentence with the return policy. The bot does not send an answer that has a contradiction.
LEGAL & COMPLIANCE
Contract summaries
A lawyer gets a short summary of a supplier contract. Pea links each summary sentence to the contract clauses. The lawyer reads the contradicted claims first.
Sample: Chatbot answers before you send them. Spans are zero-based, end-exclusive Unicode character positions in the text that you send.
REQUEST · POST /v1/alignments
{
"text": "Returns are free for 60 days. We refund to the original payment method.",
"sources": [
{
"id": "return_policy",
"text": "Returns are free for 30 days. Refunds go to the original payment method."
}
],
"claims": "sentences"
}
ILLUSTRATIVE RESPONSE
{
"claims": [
{
"span": [0, 29],
"verdict": {
"supported": 0.02,
"contradicted": 0.95,
"not_found": 0.03
},
"evidence": [
{
"source": "return_policy",
"span": [0, 29],
"relation": "contradicts"
}
]
},
{
"span": [30, 71],
"verdict": {
"supported": 0.91,
"contradicted": 0.02,
"not_found": 0.07
},
"evidence": [
{
"source": "return_policy",
"span": [30, 72],
"relation": "supports"
}
]
}
]
}
Proposed · Not available
3. Number with a range
POST /v1/predict · estimate
Ask for a number. Pea gives a median and a range, for example 10 hours, with a range from 3 to 31 hours.
Problem with Jev-style calls. Jev Score gives a maximum of ten levels that you must select before the call. Its average assumes equal steps between the levels. It cannot give a range for a quantity.
SOFTWARE ENGINEERING
Review time for a pull request
A team bot sends the diff size and the review queue. Pea gives the remaining work hours as a range. The bot shows the 0.9 quantile to the team.
LOGISTICS & SUPPLY CHAIN
Delay in a supplier email
A planner sends supplier emails about late deliveries. Pea gives the delay in days as a range. The ERP keeps the order date, and the planner reads each large range.
BANKING & INSURANCE
Repair cost from a claim
An insurer asks for the repair cost in a car damage claim. The insurer sends each claim with a large range to an assessor. Pea does not set the paid amount.
Sample: Review time for a pull request.
REQUEST · POST /v1/predict
{
"state": {
"pull_request": "#5120: Change the cache layer of the billing service.",
"files_changed": 14,
"lines_changed": 820,
"reviewers": 2
},
"questions": {
"review_hours": {
"type": "estimate",
"question": "How many working hours until the review is complete?",
"unit": "hours",
"range": [0, 120],
"quantiles": [0.1, 0.5, 0.9]
}
}
}
ILLUSTRATIVE RESPONSE
{
"answers": {
"review_hours": {
"type": "estimate",
"estimate": 9.5,
"unit": "hours",
"quantiles": {"0.1": 3.0, "0.5": 9.5, "0.9": 31.0}
}
}
}
Proposed · Not available
4. Label every part of a document
POST /v1/annotate
Send one long document. Pea answers your questions for each sentence, paragraph or line. It uses the full document as context.
Problem with Jev-style calls. With Jev, you send the full document again for each part, or you send the part without its context. A long document can be larger than the request limit.
SOFTWARE ENGINEERING
Comments on each part of a code review
A review bot sends a pull request diff and divides it into hunks. Pea answers whether each hunk has a defect. The bot adds comments, but it does not block the merge.
LEGAL & COMPLIANCE
Renewal clauses in a contract
A legal team sends a 60-page supplier contract. Pea marks each clause with an automatic renewal or a penalty. A lawyer confirms each mark.
PUBLIC SECTOR
Sections of a permit application
A clerk sends a building permit application. Pea checks the free-text evidence in each section. The form rules check the required fields, and the clerk makes the decision.
Sample: Renewal clauses in a contract. The sample shows a short version of the contract and of the response, without the probability maps. Spans are zero-based, end-exclusive Unicode character positions.
REQUEST · POST /v1/annotate
{
"document": "1. Definitions. …\n7. Renewal. This agreement renews automatically for 12 months unless a party gives notice 90 days before the end date.\n8. Liability. …",
"segment": "paragraph",
"questions": {
"auto_renewal": {
"type": "noul",
"statement": "This clause renews the agreement automatically."
},
"subject": {
"type": "choice",
"question": "What does this clause control?",
"options": {
"definitions": "Terms and their meanings",
"term": "Duration or renewal",
"liability": "Limits of liability"
}
}
}
}
ILLUSTRATIVE RESPONSE
{
"segments": [
{
"span": [0, 17],
"answers": {
"auto_renewal": {"type": "noul", "noul": 0.01},
"subject": {"type": "choice", "choice": "definitions"}
}
},
{
"span": [18, 136],
"answers": {
"auto_renewal": {"type": "noul", "noul": 0.97},
"subject": {"type": "choice", "choice": "term"}
}
},
{
"span": [137, 152],
"answers": {
"auto_renewal": {"type": "noul", "noul": 0.02},
"subject": {"type": "choice", "choice": "liability"}
}
}
],
"summary": {"auto_renewal": {"max": 0.97, "segment": 1}}
}
Proposed · Not available
5. Watch a conversation
POST /v1/states · /events
Send a conversation once. Then add each new message. Pea keeps the earlier messages and checks your standing questions after each new message.
Problem with Jev-style calls. With Jev, you send the full conversation again after each message. The cost and the time increase with each message. A long conversation can be larger than the request limit.
SOFTWARE ENGINEERING
Incident channel status
An incident bot adds each chat message to a state. A standing question asks if the team states a root cause. The on-call engineer confirms the status before the status page changes.
BANKING & INSURANCE
Investment advice in a live chat
A bank adds each chat message to a state. A standing question asks if the agent gives personal investment advice. An alert tells a supervisor. The alert helps the supervisor and is not a compliance control.
SECURITY OPERATIONS
Account abuse in a user session
After a security rule fires, a security tool adds the session events to a state. An alert tells an analyst when the abuse probability is more than 0.8. The abuse system keeps the enforcement.
Sample: Investment advice in a live chat. An earlier call to POST /v1/states made the state st_7Hq2 with two standing questions: advice and hardship. The alert limit for advice is 0.8.
REQUEST · POST /v1/states/st_7Hq2/events
{
"event": {
"role": "agent",
"text": "With your savings, I would move everything into the technology fund."
}
}
ILLUSTRATIVE RESPONSE
{
"seq": 14,
"answers": {
"advice": {
"type": "noul",
"noul": 0.91,
"probabilities": {"true": 0.91, "false": 0.09}
},
"hardship": {
"type": "noul",
"noul": 0.07,
"probabilities": {"true": 0.07, "false": 0.93}
}
},
"alerts": ["advice"],
"billed_input_tokens": 19
}
Proposed · Not available
6. Use your corrections
POST /v1/feedback
Send the correct answer when Pea is wrong. Your own version of the model uses your corrections and gets a new calibration.
Problem with Jev-style calls. Jev uses the same model for all customers, so corrections do not change later answers. You can only add examples to each request, and you pay for them each time.
SOFTWARE ENGINEERING
False defect warnings
A review bot marks a hunk as a defect. The reviewer sends the correct answer: false. The next scheduled update uses the correction.
HR & RECRUITING
Document types in applications
A recruiter changes a document label from “certificate” to “work history”. The next update uses the document types of this team.
MEDIA & CONTENT MODERATION
Moderation decisions
A moderator restores a post that Pea marked as a policy breach. A second moderator confirms the correction. The next update uses it as an example of the local policy.
Sample: Moderation decisions.
REQUEST · POST /v1/feedback
{
"request_id": "req_81f2",
"question": "policy_breach",
"correct": false,
"source": "moderator_review"
}
ILLUSTRATIVE RESPONSE
{
"accepted": true,
"corrections_pending": 412,
"next_update": "2026-10-14T02:00:00Z",
"model": "pea-acme-v7"
}
Proposed · Not available
7. If so, then…
POST /v1/predict · given
Ask a question that assumes the answer to another question. Pea gives the conditional and the joint probability in one call.
Problem with Jev-style calls. You can write the assumption into a Jev question. But Jev answers each question separately, so it does not combine the answers or keep them consistent.
SOFTWARE ENGINEERING
Breaking change and major version
A release bot asks if a change breaks the API. A second question asks if users must change their code, given a break. The bot sets a major version when the joint probability is above your limit.
CUSTOMER SUPPORT & E-COMMERCE
Reason for a refund
A shop asks if an email requests a refund. A second question asks for the reason, given a refund request. Pea sends both answers in one call.
BANKING & INSURANCE
Water damage and invoices
An insurer asks if a claim is for water damage. A second question asks if the claim needs a plumber invoice, given water damage.
Sample: Reason for a refund.
REQUEST · POST /v1/predict
{
"state": "I was charged twice for the same headphones. Please return the extra payment.",
"questions": {
"intent": {
"type": "choice",
"question": "What does the customer want?",
"options": {
"refund": "Money back",
"cancel": "Cancel an order",
"other": "Something else"
}
},
"reason": {
"type": "choice",
"question": "Why does the customer want a refund?",
"given": {"intent": "refund"},
"options": {
"duplicate": "The customer paid twice",
"not_received": "The item did not arrive",
"unwanted": "The customer does not want the item"
}
}
}
}
ILLUSTRATIVE RESPONSE
{
"answers": {
"intent": {
"type": "choice",
"choice": "refund",
"probabilities": {"refund": 0.93, "cancel": 0.05, "other": 0.02}
},
"reason": {
"type": "choice",
"choice": "duplicate",
"probabilities": {
"duplicate": 0.94,
"not_received": 0.02,
"unwanted": 0.04
},
"p_given": 0.93,
"joint": {
"duplicate": 0.87,
"not_received": 0.02,
"unwanted": 0.04
}
}
}
}
Proposed · Not available
8. Pick the correct record
POST /v1/predict · bind
Send a list of records in the state. Pea picks the matching record, or it tells you that no record matches. It cannot invent an ID.
Problem with Jev-style calls. With Jev, you must write each record as a Choice option. Then you must find the record that matches the answer.
SOFTWARE ENGINEERING
The service that owns an error
An error bot sends a stack trace and the list of services when the package name does not identify the owner. Pea picks the service, and the bot shows the probability with the page.
CUSTOMER SUPPORT & E-COMMERCE
The order in a complaint
A customer writes about the headphones from March. Pea picks the correct order from the three orders of the customer, or it returns __absent__.
LOGISTICS & SUPPLY CHAIN
Delivery scans and purchase orders
A warehouse sends a delivery scan and the open purchase orders. Pea picks the order or returns __absent__. A person confirms the match before the system books the receipt.
Sample: The order in a complaint.
REQUEST · POST /v1/predict
{
"state": {
"message": "I was charged twice for the headphones that I bought in March.",
"orders": [
{
"id": "ord_1042",
"date": "2026-01-14",
"items": ["USB-C cable"]
},
{
"id": "ord_1187",
"date": "2026-03-02",
"items": ["Studio headphones"]
},
{
"id": "ord_1233",
"date": "2026-03-28",
"items": ["Headphone case"]
}
]
},
"questions": {
"order": {
"type": "bind",
"question": "Which order is the customer writing about?",
"candidates": "orders",
"key": "id"
}
}
}
ILLUSTRATIVE RESPONSE
{
"answers": {
"order": {
"type": "bind",
"bind": "ord_1187",
"probabilities": {
"ord_1042": 0.01,
"ord_1187": 0.9,
"ord_1233": 0.06,
"__absent__": 0.03
}
}
}
}
Proposed · Not available
9. Step-by-step checks
POST /v1/flows
Define a sequence of checks. Pea does each step, obeys your conditions and gives the result with a record of each step.
Problem with Jev-style calls. With Jev, your code must make each call, apply the conditions and write the audit record.
SOFTWARE ENGINEERING
Release checklist
CI runs the tests and the migrations. A release tool then runs a flow for the API break and the release notes. The release notes include the audit record.
PUBLIC SECTOR
Documents in a benefit application
A benefits office runs a flow that finds the documents that are not in an application. The flow stops with needs_input for each document. A caseworker makes all eligibility decisions.
HEALTHCARE ADMINISTRATION
Prior authorisation files
The document store checks that a prior authorisation form is in the file. Then Pea compares the treatment code with the form text. A billing person checks each mismatch.
Sample: Documents in a benefit application. You set the thresholds for each condition. A step that matches no condition goes to the otherwise branch. The response is shorter than the full format.
REQUEST · POST /v1/flows
{
"state": {
"application": "…",
"documents": ["id_card", "rental_contract"]
},
"steps": [
{
"id": "residence",
"question": {
"type": "noul",
"statement": "The file contains a proof of residence."
}
},
{
"id": "income",
"when": {"residence": {"above": 0.9}},
"question": {
"type": "noul",
"statement": "The file contains a proof of income."
}
},
{
"id": "payslip",
"when": {"income": {"below": 0.5}},
"requires": "payslip"
}
],
"otherwise": "review"
}
ILLUSTRATIVE RESPONSE
{
"flow_id": "flow_52c",
"status": "needs_input",
"needs": "payslip",
"steps": [
{
"id": "residence",
"answer": {"type": "noul", "noul": 0.97},
"decision": "above 0.9"
},
{
"id": "income",
"answer": {"type": "noul", "noul": 0.06},
"decision": "below 0.5"
},
{"id": "payslip", "status": "needs_input"}
]
}
Proposed · Not available
10. Rank with probabilities
POST /v1/rankings
Send a list of candidates. Pea gives the probability that each candidate is the best, and the probability that it is in your top k.
Problem with Jev-style calls. Jev Choice gives the probability that an option is the best. It does not give top-k probabilities, and it accepts a maximum of 255 options.
SOFTWARE ENGINEERING
The cause of a failed deployment
An on-call tool sends the changes before an outage. Pea ranks the changes by the probability that they caused the outage. The engineer checks the top two changes first.
MANUFACTURING
Fault codes after a line stop
A production line sends its recent fault codes after a stop. A technician examines the codes with the highest top-3 probability first.
MEDIA & CONTENT MODERATION
A review queue
A moderation team sends a batch of 50 reported posts to Pea. The moderators review the posts with the highest top-10 probability first. A time limit still applies to the oldest severe report.
Sample: The cause of a failed deployment.
REQUEST · POST /v1/rankings
{
"state": "Checkout errors started at 14:02. Error: connection pool exhausted.",
"question": "Which change caused the outage?",
"candidates": {
"chg_311": "Lower the database pool size from 50 to 10",
"chg_309": "Add a retry to the payment client",
"chg_310": "Update the logging library",
"chg_305": "Change the colour of the checkout button"
},
"top_k": 2
}
ILLUSTRATIVE RESPONSE
{
"ranking": [
{"id": "chg_311", "p_best": 0.62, "p_top_k": 0.88},
{"id": "chg_309", "p_best": 0.21, "p_top_k": 0.63},
{"id": "chg_310", "p_best": 0.12, "p_top_k": 0.37},
{"id": "chg_305", "p_best": 0.05, "p_top_k": 0.12}
]
}
Proposed · Not available
11. Select effort
POST /v1/predict · effort
Select fast, standard or careful effort for each question. The response tells you which effort Pea uses. We will test if careful effort gives better answers before we promise that result.
Problem with Jev-style calls. Jev has one speed. For a difficult case, you must send the question to a larger and slower model.
SOFTWARE ENGINEERING
Style checks and security checks
A CI job uses fast effort for a style question. It uses careful effort for a security question about the same change.
SECURITY OPERATIONS
New-file reports
A threat index checks the known file hashes. For a new file, Pea uses careful effort on the analysis report. An analyst checks the result.
LEGAL & COMPLIANCE
Policy exceptions
A reviewer uses careful effort for a policy exception that refers to many other clauses.
Sample: Style checks and security checks.
REQUEST · POST /v1/predict
{
"state": "Diff: replace the shared token check in three services with a new library.",
"questions": {
"style": {
"type": "noul",
"statement": "The change follows the style guide.",
"effort": "fast"
},
"security": {
"type": "noul",
"statement": "The change needs a security review.",
"effort": "careful"
}
}
}
ILLUSTRATIVE RESPONSE
{
"answers": {
"style": {
"type": "noul",
"noul": 0.94,
"probabilities": {"true": 0.94, "false": 0.06},
"effort_used": "fast"
},
"security": {
"type": "noul",
"noul": 0.85,
"probabilities": {"true": 0.85, "false": 0.15},
"effort_used": "careful"
}
}
}
Not in this list
We do not plan new model types for text generation, embeddings or scans of raw bytes. Other vendors sell tools for these functions. Pea can score the output of these tools with Choice, Noul and Score.
Tell us which API you need
Send the API name and your use case. Your answer helps us decide the order of work.