Add a labeled case to a decision corpus

POST /v1/agents/{agent_id}/decision-corpora/{corpus_id}/cases

Property	Value
Operation	`create_decision_case`
Group	Decision corpora
Scope	`agents:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `decision_case.create` (mutation)
Released in	1.58.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Adds a case and raises the corpus's version (1.58.0): a synthetic case with its state, or a production case naming a Call and Turn whose redacted caller text the api copies, an audited content read and write that needs the Organization's opt-in (decision_case_production_not_allowed), from 1.59.0 its production_decision_cases. From 1.59.0 copying a Turn's caller text reads the class transcripts of the Call: an API key needs transcripts:read beside agents:write, and a Member a cell or grant get_call_content_access answers allowed for it, or the create is 403 forbidden as a read of the case would be. The Audit event records the case, never its state.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the agents:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/agents/agt_.../decision-corpora/dcp_.../cases" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "synthetic",
    "expected": {}
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/agents/agt_.../decision-corpora/dcp_.../cases`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "source": "synthetic",
    "expected": {}
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/agents/agt_.../decision-corpora/dcp_.../cases",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "source": "synthetic",
        "expected": {},
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`agent_id`	path	AgentId	yes	The id of an Agent: `agt_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`corpus_id`	path	DecisionCorpusId	yes	The id of a decision corpus: `dcp_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: DecisionCaseCreateRequest.

Field	Type	Required	Description
`call_id`	CallId	no	A `production` case only.
`expected`	map of DecisionExpectedAnswer	yes	The answer expected of each question by id; a question left out is not scored.
`source`	one of `"synthetic"`, `"production"`	yes	`synthetic` with its `state`, or `production` with its `call_id` and `turn_seq`.
`state`	DecisionStateDocument	no	A `synthetic` case only.
`turn_seq`	integer	no	A `production` case only.

Responses

Status	Content type	Shape	Error codes
`201`	`application/json`	DecisionCase
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`decision_corpus_archived`, `idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `201` answer

The shape is DecisionCase.

Field	Type	Required	Description
`call_id`	CallId or null	yes	The Call of a `production` case; null otherwise.
`corpus_id`	DecisionCorpusId	yes
`created_at`	Timestamp	yes
`expected`	map of DecisionExpectedAnswer	yes	The answer expected of each question by id; a question left out is not scored.
`id`	DecisionCaseId	yes
`labelled_by`	ActorRef	yes
`object`	`"decision_case"`	yes
`source`	DecisionCaseSource	yes
`state`	DecisionStateDocument	yes	The state the questions are asked of; content, read under an audited content read. From 1.59.0 the state of a `production` case is of the content class `transcripts` of its Call (the reads of the case say what that asks of the reader); the state of another case is not Call content.
`turn_seq`	integer or null	yes	The Turn of a `production` case; null otherwise.